openapi: 3.1.0
info:
  title: ShipStation V1 API (Legacy)
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/license/mit/
  contact:
    name: ShipStation Support
    email: support@shipstation.com
    url: https://www.shipstation.com/contact/
  description: >
    The ShipStation V1 API (Legacy) provides comprehensive functionality for
    managing orders, shipments, carriers, and more within the ShipStation
    platform.


    ## Getting Started

    New integrations should use [ShipStation API
    V2](/apis/@shipstation-v2/openapi.yaml) whenever possible. This V1 API is
    maintained for existing integrations.
servers:
  - url: https://ssapi.shipstation.com
    description: Production Server
tags:
  - name: accounts
    description: Account management and tag operations
    x-displayName: Accounts
  - name: carriers
    description: Carrier information and package/service listings
    x-displayName: Carriers
  - name: customers
    description: Customer management
    x-displayName: Customers
  - name: fulfillments
    description: Fulfillment operations
    x-displayName: Fulfillments
  - name: orders
    description: Order management and operations
    x-displayName: Orders
  - name: products
    description: Product catalog management
    x-displayName: Products
  - name: shipments
    description: Shipment operations and rate shopping
    x-displayName: Shipments
  - name: stores
    description: Store configuration and management
    x-displayName: Stores
  - name: users
    description: User management
    x-displayName: Users
  - name: warehouses
    description: Warehouse and fulfillment location management
    x-displayName: Warehouses
  - name: webhooks
    description: Webhook subscription management
    x-displayName: Webhooks
paths:
  /orders/createorder:
    post:
      summary: Create or update order
      description: >
        Create a new order or update an existing order. If the `orderKey` is
        specified, ShipStation will attempt to locate the order with that key.
        If found, the existing order will be updated. If not found, a new order
        will be created with that `orderKey`.


        **Note:** This call does not currently support partial updates. The
        entire resource must be provided in the body of the request.


        Only orders in an open status (`awaiting_payment`, `awaiting_shipment`,
        `on_hold`) can be updated. Orders in `cancelled` and `shipped` states
        may not be updated.
      tags:
        - orders
      operationId: create_update_order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              basic_order:
                summary: Basic order example
                value:
                  orderNumber: TEST-ORDER-API-DOCS
                  orderKey: 0f6bec18-3e89-4771-83aa-f392d84f4c74
                  orderDate: '2015-06-29T08:46:27.000Z'
                  paymentDate: '2015-06-29T08:46:27.000Z'
                  shipByDate: '2015-07-05T00:00:00.000Z'
                  orderStatus: awaiting_shipment
                  customerUsername: headhoncho@whitehouse.gov
                  customerEmail: headhoncho@whitehouse.gov
                  billTo:
                    name: The President
                    country: US
                  shipTo:
                    name: The President
                    company: US Govt
                    street1: 1600 Pennsylvania Ave
                    street2: Oval Office
                    city: Washington
                    state: DC
                    postalCode: '20500'
                    country: US
                    phone: 555-555-5555
                    residential: true
                  items:
                    - lineItemKey: vd08-MSLbtx
                      sku: ABC123
                      name: 'Test item #1'
                      quantity: 2
                      unitPrice: 99.99
                      weight:
                        value: 24
                        units: ounces
                  amountPaid: 218.73
                  taxAmount: 5
                  shippingAmount: 10
                  customerNotes: Please ship as soon as possible!
                  requestedShippingService: Priority Mail
      responses:
        '200':
          description: Order created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                success:
                  summary: Successful response
                  value:
                    orderId: 93348442
                    orderNumber: TEST-ORDER-API-DOCS
                    orderKey: 0f6bec18-3e89-4771-83aa-f392d84f4c74
                    orderDate: '2015-06-29T08:46:27.000Z'
                    createDate: '2016-01-12T16:03:06.893Z'
                    modifyDate: '2016-01-12T16:03:06.893Z'
                    paymentDate: '2015-06-29T08:46:27.000Z'
                    shipByDate: '2015-07-05T00:00:00.000Z'
                    orderStatus: awaiting_shipment
                    customerId: 37701499
                    customerUsername: headhoncho@whitehouse.gov
                    customerEmail: headhoncho@whitehouse.gov
                    orderTotal: 194.43
                    amountPaid: 218.73
                    taxAmount: 5
                    shippingAmount: 10
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders:
    get:
      summary: List orders
      description: >
        Obtains a list of orders that match the specified criteria. All filters
        are optional. If no filters are provided, recent orders will be
        returned.
      tags:
        - orders
      operationId: list_orders
      parameters:
        - name: customerName
          in: query
          schema:
            type: string
          description: Returns orders that match the specified customer name
        - name: itemKeyword
          in: query
          schema:
            type: string
          description: >
            Returns orders containing items matching the specified keyword.
            Fields searched are Sku, Description, and Options.
        - name: createDateStart
          in: query
          schema:
            type: string
            format: date-time
          description: Returns orders created in ShipStation after the specified date
        - name: createDateEnd
          in: query
          schema:
            type: string
            format: date-time
          description: Returns orders created in ShipStation before the specified date
        - name: modifyDateStart
          in: query
          schema:
            type: string
            format: date-time
          description: Returns orders modified after the specified date
        - name: modifyDateEnd
          in: query
          schema:
            type: string
            format: date-time
          description: Returns orders modified before the specified date
        - name: orderDateStart
          in: query
          schema:
            type: string
            format: date-time
          description: Returns orders greater than the specified date
        - name: orderDateEnd
          in: query
          schema:
            type: string
            format: date-time
          description: Returns orders less than or equal to the specified date
        - name: orderNumber
          in: query
          schema:
            type: string
          description: Filter by order number (performs a "starts with" search)
        - name: orderStatus
          in: query
          schema:
            type: string
            enum:
              - awaiting_payment
              - awaiting_shipment
              - pending_fulfillment
              - shipped
              - on_hold
              - cancelled
              - rejected_fulfillment
          description: Filter by order status
        - name: paymentDateStart
          in: query
          schema:
            type: string
            format: date-time
          description: Returns orders paid after the specified date
        - name: paymentDateEnd
          in: query
          schema:
            type: string
            format: date-time
          description: Returns orders paid before the specified date
        - name: storeId
          in: query
          schema:
            type: integer
          description: Filter orders to a single store
        - $ref: '#/components/parameters/sort_by_param'
        - $ref: '#/components/parameters/sort_dir_param'
        - $ref: '#/components/parameters/page_param'
        - $ref: '#/components/parameters/page_size_param'
      responses:
        '200':
          description: List of orders retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  total:
                    type: integer
                    description: Total number of orders matching criteria
                    example: 2
                  page:
                    type: integer
                    description: Current page number
                    example: 1
                  pages:
                    type: integer
                    description: Total number of pages
                    example: 1
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/{orderId}:
    get:
      summary: Get order
      description: Retrieves a single order by its ID
      tags:
        - orders
      operationId: get_order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
          description: The system-generated order ID
          example: 93348442
      responses:
        '200':
          description: Order retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
    delete:
      summary: Delete order
      description: >
        Removes order from ShipStation's UI. This is a "soft" delete action so
        the order will still exist in the database, but will be set to inactive.
      tags:
        - orders
      operationId: delete_order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
          description: The order ID to delete
          example: 93348442
      responses:
        '200':
          description: Order deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: The requested order has been deleted.
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/createorders:
    post:
      summary: Create or update multiple orders
      description: >
        Create or update multiple orders in one request. If the `orderKey` is
        specified, ShipStation will attempt to locate the order with that key.
        If found, the existing order will be updated. If not found, a new order
        will be created.


        For split orders, the `orderKey` is always required when creating or
        updating orders, and the `orderId` is always required for updates.


        This call does not currently support partial updates; the entire
        resource must be provided in the body of the request.


        Only orders in an open status (`awaiting_payment`, `awaiting_shipment`,
        `pending_fulfillment`, `on_hold`) can be updated. Orders in `cancelled`
        or `shipped` status may not be updated.
      tags:
        - orders
      operationId: create_update_multiple_orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              maxItems: 100
              items:
                $ref: '#/components/schemas/Order'
            examples:
              multiple_orders:
                summary: Multiple orders example
                value:
                  - orderNumber: TEST-ORDER-API-DOCS-01
                    orderKey: 0f6bec18-3e89-4881-83aa-f392d84f4c74
                    orderDate: '2015-06-29T08:46:27.000Z'
                    orderStatus: awaiting_shipment
                    customerEmail: headhoncho@whitehouse.gov
                    shipTo:
                      name: The President
                      company: US Govt
                      street1: 1600 Pennsylvania Ave
                      city: Washington
                      state: DC
                      postalCode: '20500'
                      country: US
                    items:
                      - sku: ABC123
                        name: 'Test item #1'
                        quantity: 2
                        unitPrice: 99.99
                  - orderNumber: TEST-ORDER-API-DOCS-02
                    orderKey: 0d6bec18-3e79-4981-83ca-f392d84f4c19
                    orderDate: '2015-06-29T08:46:27.000Z'
                    orderStatus: awaiting_shipment
                    customerEmail: headhoncho@whitehouse.gov
                    shipTo:
                      name: The President
                      street1: 1600 Pennsylvania Ave
                      city: Washington
                      state: DC
                      postalCode: '20500'
                      country: US
                    items:
                      - sku: XYZ789
                        name: 'Test item #2'
                        quantity: 1
                        unitPrice: 49.99
      responses:
        '200':
          description: Orders created or updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  hasErrors:
                    type: boolean
                    description: Whether any errors occurred
                    example: false
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        orderId:
                          type: integer
                          example: 123456789
                        orderNumber:
                          type: string
                          example: TEST-ORDER-API-DOCS-01
                        orderKey:
                          type: string
                          example: 0f6bec18-3e89-4881-83aa-f392d84f4c74
                        success:
                          type: boolean
                          example: true
                        message:
                          type: string
                          example: ''
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/addtag:
    post:
      summary: Add tag to order
      description: Adds a tag to an order
      tags:
        - orders
      operationId: add_tag_to_order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderId
                - tagId
              properties:
                orderId:
                  type: integer
                  description: Order ID to tag
                  example: 123456
                tagId:
                  type: integer
                  description: Tag ID to apply
                  example: 1234
      responses:
        '200':
          description: Tag added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Tag added successfully.
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/removetag:
    post:
      summary: Remove tag from order
      description: Removes a tag from the specified order
      tags:
        - orders
      operationId: remove_tag_from_order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderId
                - tagId
              properties:
                orderId:
                  type: integer
                  description: Order ID
                  example: 123456
                tagId:
                  type: integer
                  description: Tag ID to remove
                  example: 1234
      responses:
        '200':
          description: Tag removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Tag removed successfully.
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/assignuser:
    post:
      summary: Assign user to order
      description: >
        Assigns a user to an order. If ANY of the orders within the array are
        not found, no orders will have a user assigned to them.
      tags:
        - orders
      operationId: assign_user_to_order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderIds
                - userId
              properties:
                orderIds:
                  type: array
                  items:
                    type: integer
                  description: Array of order IDs to assign
                  example:
                    - 123456789
                    - 12345679
                userId:
                  type: string
                  description: User GUID to assign to orders
                  example: 123456AB-ab12-3c4d-5e67-89f1abc1defa
      responses:
        '200':
          description: User assigned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: User assigned successfully.
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/unassignuser:
    post:
      summary: Unassign user from order
      description: >
        Unassigns a user from an order. If ANY of the orders within the array
        are not found, no orders will have their users unassigned.
      tags:
        - orders
      operationId: unassign_user_from_order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderIds
              properties:
                orderIds:
                  type: array
                  items:
                    type: integer
                  description: Array of order IDs to unassign
                  example:
                    - 123456789
                    - 12345679
      responses:
        '200':
          description: User unassigned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: User unassigned successfully.
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/holduntil:
    post:
      summary: Hold order until date
      description: >
        Changes the status of the order to On Hold until the specified date,
        when the status will automatically change to Awaiting Shipment.
      tags:
        - orders
      operationId: hold_order_until
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderId
                - holdUntilDate
              properties:
                orderId:
                  type: integer
                  description: Order ID to hold
                  example: 1072467
                holdUntilDate:
                  type: string
                  format: date
                  description: Date when order moves from on_hold to awaiting_shipment
                  example: '2014-12-01'
      responses:
        '200':
          description: Order held successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Order held successfully.
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/restorefromhold:
    post:
      summary: Restore order from hold
      description: >
        Changes the status of the order from On Hold to Awaiting Shipment. This
        endpoint is used when a holdUntilDate is attached to an order.
      tags:
        - orders
      operationId: restore_order_from_hold
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderId
              properties:
                orderId:
                  type: integer
                  description: Order ID to restore
                  example: 1234567
      responses:
        '200':
          description: Order restored successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: The requested order has been restored
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/markasshipped:
    post:
      summary: Mark order as shipped
      description: Marks an order as Shipped without creating a label in ShipStation
      tags:
        - orders
      operationId: mark_order_as_shipped
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderId
                - carrierCode
              properties:
                orderId:
                  type: integer
                  description: Order ID to mark as shipped
                  example: 93348442
                carrierCode:
                  type: string
                  description: Carrier code
                  example: usps
                shipDate:
                  type: string
                  format: date
                  description: Date order was shipped
                  example: '2014-04-01'
                trackingNumber:
                  type: string
                  description: Tracking number
                  example: '913492493294329421'
                notifyCustomer:
                  type: boolean
                  description: Whether to notify customer
                  default: false
                  example: true
                notifySalesChannel:
                  type: boolean
                  description: Whether to notify sales channel
                  default: false
                  example: true
      responses:
        '200':
          description: Order marked as shipped successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: integer
                    example: 123456789
                  orderNumber:
                    type: string
                    example: ABC123
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /orders/listbytag:
    get:
      summary: List orders by tag
      description: Obtains a list of orders that have been tagged with the specified tagId
      tags:
        - orders
      operationId: list_orders_by_tag
      parameters:
        - name: orderStatus
          in: query
          required: true
          schema:
            type: string
            enum:
              - awaiting_payment
              - awaiting_shipment
              - pending_fulfillment
              - shipped
              - on_hold
              - cancelled
          description: The order's status
          example: awaiting_shipment
        - name: tagId
          in: query
          required: true
          schema:
            type: integer
          description: ID of the tag
          example: 53974
        - $ref: '#/components/parameters/page_param'
        - $ref: '#/components/parameters/page_size_param'
      responses:
        '200':
          description: List of orders retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  total:
                    type: integer
                    description: Total number of orders
                    example: 1
                  page:
                    type: integer
                    description: Current page number
                    example: 1
                  pages:
                    type: integer
                    description: Total number of pages
                    example: 1
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /shipments/getrates:
    post:
      summary: Get shipping rates
      description: >
        Retrieves shipping rates for the specified shipping details. Use this
        endpoint to compare rates across different carriers and services before
        creating a label.
      tags:
        - shipments
      operationId: get_rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - carrierCode
                - fromPostalCode
                - toCountry
                - toPostalCode
                - weight
              properties:
                carrierCode:
                  type: string
                  description: Carrier code to get rates from
                  example: fedex
                serviceCode:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Specific service code (optional)
                packageCode:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Package type code (optional)
                fromPostalCode:
                  type: string
                  description: Origin postal code
                  example: '78703'
                toCountry:
                  type: string
                  description: Destination country (two-letter ISO code)
                  example: US
                toPostalCode:
                  type: string
                  description: Destination postal code
                  example: '20500'
                toState:
                  type: string
                  description: Destination state (required for UPS)
                  example: DC
                toCity:
                  type: string
                  description: Destination city (optional)
                  example: Washington
                weight:
                  $ref: '#/components/schemas/Weight'
                dimensions:
                  anyOf:
                    - $ref: '#/components/schemas/Dimensions'
                    - type: 'null'
                confirmation:
                  type: string
                  enum:
                    - none
                    - delivery
                    - signature
                    - adult_signature
                    - direct_signature
                  description: Delivery confirmation type
                  example: delivery
                residential:
                  type: boolean
                  description: Whether destination is residential
                  example: false
      responses:
        '200':
          description: List of available shipping rates
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    serviceName:
                      type: string
                      example: FedEx Ground®
                    serviceCode:
                      type: string
                      example: fedex_ground
                    shipmentCost:
                      type: number
                      example: 8.25
                    otherCost:
                      type: number
                      example: 0.33
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /shipments/createlabel:
    post:
      summary: Create shipping label
      description: >
        Creates a shipping label. The `labelData` field returned in the response
        is a base64 encoded PDF value. You can decode and save the output as a
        PDF file to retrieve a printable label.


        **IMPORTANT:** You must have at least one active Manual Store on your
        ShipStation account to create labels with this endpoint.
      tags:
        - shipments
      operationId: create_shipment_label
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - carrierCode
                - serviceCode
                - packageCode
                - shipDate
                - weight
                - shipFrom
                - shipTo
              properties:
                carrierCode:
                  type: string
                  description: Carrier code
                  example: fedex
                serviceCode:
                  type: string
                  description: Service code
                  example: fedex_ground
                packageCode:
                  type: string
                  description: Package type code
                  example: package
                confirmation:
                  type: string
                  enum:
                    - none
                    - delivery
                    - signature
                    - adult_signature
                    - direct_signature
                  description: Delivery confirmation type
                  example: delivery
                shipDate:
                  type: string
                  format: date
                  description: Ship date
                  example: '2014-04-03'
                weight:
                  $ref: '#/components/schemas/Weight'
                dimensions:
                  anyOf:
                    - $ref: '#/components/schemas/Dimensions'
                    - type: 'null'
                shipFrom:
                  $ref: '#/components/schemas/Address'
                shipTo:
                  $ref: '#/components/schemas/Address'
                insuranceOptions:
                  anyOf:
                    - $ref: '#/components/schemas/InsuranceOptions'
                    - type: 'null'
                internationalOptions:
                  anyOf:
                    - $ref: '#/components/schemas/InternationalOptions'
                    - type: 'null'
                advancedOptions:
                  anyOf:
                    - $ref: '#/components/schemas/AdvancedOptions'
                    - type: 'null'
                testLabel:
                  type: boolean
                  description: Whether to create a test label
                  example: false
      responses:
        '200':
          description: Label created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  shipmentId:
                    type: integer
                    example: 123456789
                  shipmentCost:
                    type: number
                    example: 8.25
                  insuranceCost:
                    type: number
                    example: 0
                  trackingNumber:
                    type: string
                    example: '9405511899564298878910'
                  labelData:
                    type: string
                    description: Base64 encoded PDF label data
                    example: JVBERi0xLjQKJeLjz9MKMiAwIG9iago...
                  formData:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Base64 encoded form data if applicable
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /shipments/voidlabel:
    post:
      summary: Void shipment label
      description: Voids the specified label by shipmentId
      tags:
        - shipments
      operationId: void_label
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shipmentId
              properties:
                shipmentId:
                  type: integer
                  description: ID of the shipment to void
                  example: 12345
      responses:
        '200':
          description: Label voided successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  approved:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Label voided successfully
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /shipments:
    get:
      summary: List shipments
      description: >
        Obtains a list of shipments that match the specified criteria.


        **Note:** Only valid shipments with labels generated in ShipStation will
        be returned. Orders that have been marked as Shipped through the UI or
        API will not appear as they are considered external shipments.
      tags:
        - shipments
      operationId: list_shipments
      parameters:
        - name: recipientName
          in: query
          schema:
            type: string
          description: Returns shipments shipped to the specified recipient name
        - name: recipientCountryCode
          in: query
          schema:
            type: string
          description: >-
            Returns shipments shipped to the specified country code (two-letter
            ISO)
        - name: orderNumber
          in: query
          schema:
            type: string
          description: Returns shipments whose orders have the specified order number
        - name: orderId
          in: query
          schema:
            type: integer
          description: Returns shipments whose orders have the specified order ID
        - name: carrierCode
          in: query
          schema:
            type: string
          description: Returns shipments shipped with the specified carrier
        - name: serviceCode
          in: query
          schema:
            type: string
          description: Returns shipments shipped with the specified shipping service
        - name: trackingNumber
          in: query
          schema:
            type: string
          description: Returns shipments with the specified tracking number
        - name: createDateStart
          in: query
          schema:
            type: string
            format: date-time
          description: Returns shipments created on or after the specified date
        - name: createDateEnd
          in: query
          schema:
            type: string
            format: date-time
          description: Returns shipments created on or before the specified date
        - name: shipDateStart
          in: query
          schema:
            type: string
            format: date
          description: Returns shipments with shipDate on or after the specified date
        - name: shipDateEnd
          in: query
          schema:
            type: string
            format: date
          description: Returns shipments with shipDate on or before the specified date
        - name: voidDateStart
          in: query
          schema:
            type: string
            format: date-time
          description: Returns shipments voided on or after the specified date
        - name: voidDateEnd
          in: query
          schema:
            type: string
            format: date-time
          description: Returns shipments voided on or before the specified date
        - name: storeId
          in: query
          schema:
            type: integer
          description: Returns shipments whose orders belong to the specified store ID
        - name: includeShipmentItems
          in: query
          schema:
            type: boolean
            default: false
          description: Specifies whether to include shipment items with results
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - ShipDate
              - CreateDate
          description: >
            Sort the responses by a set value. If left empty, the response will
            be sorted by ascending createDate.
        - $ref: '#/components/parameters/sort_dir_param'
        - $ref: '#/components/parameters/page_param'
        - $ref: '#/components/parameters/page_size_param'
      responses:
        '200':
          description: List of shipments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  shipments:
                    type: array
                    items:
                      type: object
                      properties:
                        shipmentId:
                          type: integer
                          example: 33974374
                        orderId:
                          type: integer
                          example: 43945660
                        orderKey:
                          type: string
                          example: 8061c220f0794a9b92460b8bae6837e4
                        userId:
                          type: string
                          example: 123456AB-ab12-3c4d-5e67-89f1abc1defa
                        orderNumber:
                          type: string
                          example: 100038-1
                        createDate:
                          type: string
                          format: date-time
                          example: '2014-10-03T06:51:33Z'
                        shipDate:
                          type: string
                          format: date
                          example: '2014-10-03'
                        shipmentCost:
                          type: number
                          example: 1.93
                        insuranceCost:
                          type: number
                          example: 0
                        trackingNumber:
                          type: string
                          example: '9400111899561704681189'
                        isReturnLabel:
                          type: boolean
                          example: false
                        batchNumber:
                          anyOf:
                            - type: string
                            - type: 'null'
                          example: '100301'
                        carrierCode:
                          type: string
                          example: stamps_com
                        serviceCode:
                          type: string
                          example: usps_first_class_mail
                        packageCode:
                          type: string
                          example: package
                        confirmation:
                          type: string
                          example: delivery
                        warehouseId:
                          anyOf:
                            - type: integer
                            - type: 'null'
                          example: 16079
                        voided:
                          type: boolean
                          example: false
                        voidDate:
                          anyOf:
                            - type: string
                            - type: 'null'
                          format: date-time
                        marketplaceNotified:
                          type: boolean
                          example: true
                        notifyErrorMessage:
                          anyOf:
                            - type: string
                            - type: 'null'
                        shipTo:
                          $ref: '#/components/schemas/Address'
                        weight:
                          $ref: '#/components/schemas/Weight'
                        dimensions:
                          anyOf:
                            - $ref: '#/components/schemas/Dimensions'
                            - type: 'null'
                        insuranceOptions:
                          $ref: '#/components/schemas/InsuranceOptions'
                        advancedOptions:
                          anyOf:
                            - $ref: '#/components/schemas/AdvancedOptions'
                            - type: 'null'
                        shipmentItems:
                          anyOf:
                            - type: array
                            - type: 'null'
                          items:
                            type: object
                            properties:
                              orderItemId:
                                type: integer
                                example: 56568665
                              lineItemKey:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              sku:
                                type: string
                                example: SQ3785739
                              name:
                                type: string
                                example: Potato Kitten
                              imageUrl:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              weight:
                                anyOf:
                                  - $ref: '#/components/schemas/Weight'
                                  - type: 'null'
                              quantity:
                                type: integer
                                example: 1
                              unitPrice:
                                type: number
                                example: 1
                              warehouseLocation:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              options:
                                anyOf:
                                  - type: array
                                  - type: 'null'
                                items:
                                  $ref: '#/components/schemas/ItemOption'
                              productId:
                                anyOf:
                                  - type: integer
                                  - type: 'null'
                                example: 7565777
                              fulfillmentSku:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                        labelData:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Base64 encoded PDF label data
                        formData:
                          anyOf:
                            - type: string
                            - type: 'null'
                  total:
                    type: integer
                    description: Total number of shipments
                    example: 2
                  page:
                    type: integer
                    description: Current page number
                    example: 1
                  pages:
                    type: integer
                    description: Total number of pages
                    example: 1
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /carriers:
    get:
      summary: List carriers
      description: List all shipping providers connected to this account
      tags:
        - carriers
      operationId: list_carriers
      responses:
        '200':
          description: List of carriers retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      example: FedEx
                    code:
                      type: string
                      example: fedex
                    accountNumber:
                      type: string
                      example: '297929999'
                    requiresFundedAccount:
                      type: boolean
                      example: false
                    balance:
                      type: number
                      example: 0
                    nickname:
                      anyOf:
                        - type: string
                        - type: 'null'
                      example: SS
                    shippingProviderId:
                      type: integer
                      example: 12348
                    primary:
                      type: boolean
                      example: true
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /carriers/addfunds:
    post:
      summary: Add funds to carrier account
      description: >
        Adds funds to a carrier account using the payment information on file.


        **IMPORTANT:** Requires approval from apisupport@shipstation.com before
        use.
      tags:
        - carriers
      operationId: add_funds_to_carrier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - carrierCode
                - amount
              properties:
                carrierCode:
                  type: string
                  description: The carrier to add funds to
                  example: fedex
                amount:
                  type: number
                  minimum: 10
                  maximum: 10000
                  description: Dollar amount to add (min $10, max $10,000)
                  example: 20
      responses:
        '200':
          description: Funds added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    example: Stamps.com
                  code:
                    type: string
                    example: stamps_com
                  accountNumber:
                    type: string
                    example: SS123
                  requiresFundedAccount:
                    type: boolean
                    example: true
                  balance:
                    type: number
                    example: 24.14
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /carriers/getcarrier:
    get:
      summary: Get carrier by code
      description: >
        Retrieves the shipping carrier account details for the specified
        carrierCode. Use this method to determine a carrier's account balance.
      tags:
        - carriers
      operationId: get_carrier
      parameters:
        - name: carrierCode
          in: query
          required: true
          schema:
            type: string
          description: The code for the carrier account to retrieve
          example: stamps_com
      responses:
        '200':
          description: Carrier retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    example: Stamps.com
                  code:
                    type: string
                    example: stamps_com
                  accountNumber:
                    type: string
                    example: SS123
                  requiresFundedAccount:
                    type: boolean
                    example: true
                  balance:
                    type: number
                    example: 24.27
                  nickname:
                    anyOf:
                      - type: string
                      - type: 'null'
                    example: null
                  shippingProviderId:
                    type: integer
                    example: 12345
                  primary:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
  /carriers/listpackages:
    get:
      summary: List packages
      description: Retrieves a list of packages for the specified carrier
      tags:
        - carriers
      operationId: list_packages
      parameters:
        - name: carrierCode
          in: query
          required: true
          schema:
            type: string
          description: The carrier's code
          example: fedex
      responses:
        '200':
          description: List of packages retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    carrierCode:
                      type: string
                      example: express_1
                    code:
                      type: string
                      example: flat_rate_envelope
                    name:
                      type: string
                      example: Flat Rate Envelope
                    domestic:
                      type: boolean
                      example: true
                    international:
                      type: boolean
                      example: true
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /carriers/listservices:
    get:
      summary: List services
      description: >-
        Retrieves the list of available shipping services provided by the
        specified carrier
      tags:
        - carriers
      operationId: list_services
      parameters:
        - name: carrierCode
          in: query
          required: true
          schema:
            type: string
          description: The carrier's code
          example: fedex
      responses:
        '200':
          description: List of services retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    carrierCode:
                      type: string
                      example: fedex
                    code:
                      type: string
                      example: fedex_ground
                    name:
                      type: string
                      example: FedEx Ground®
                    domestic:
                      type: boolean
                      example: true
                    international:
                      type: boolean
                      example: false
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /stores:
    get:
      summary: List stores
      description: Retrieve the list of installed stores on the account
      tags:
        - stores
      operationId: list_stores
      parameters:
        - name: showInactive
          in: query
          schema:
            type: boolean
          description: Whether to include inactive stores
        - name: marketplaceId
          in: query
          schema:
            type: integer
          description: Filter by marketplace type
      responses:
        '200':
          description: List of stores retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    storeId:
                      type: integer
                      example: 12345
                    storeName:
                      type: string
                      example: My Shopify Store
                    marketplaceId:
                      type: integer
                      example: 36
                    marketplaceName:
                      type: string
                      example: Shopify
                    active:
                      type: boolean
                      example: true
                    createDate:
                      type: string
                      format: date-time
                    modifyDate:
                      type: string
                      format: date-time
                    autoRefresh:
                      type: boolean
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /stores/{storeId}:
    get:
      summary: Get store
      description: Retrieves information for a specific store by its ID
      tags:
        - stores
      operationId: get_store
      parameters:
        - name: storeId
          in: path
          required: true
          schema:
            type: integer
          description: Unique identifier for the store
          example: 12345
      responses:
        '200':
          description: Store retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  storeId:
                    type: integer
                    example: 12345
                  storeName:
                    type: string
                    example: My Shopify Store
                  marketplaceId:
                    type: integer
                    example: 36
                  marketplaceName:
                    type: string
                    example: Shopify
                  active:
                    type: boolean
                    example: true
                  createDate:
                    type: string
                    format: date-time
                  modifyDate:
                    type: string
                    format: date-time
                  autoRefresh:
                    type: boolean
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
    put:
      summary: Update store
      description: >
        Updates an existing store. This call does not currently support partial
        updates. The entire resource must be provided in the body of the
        request.
      tags:
        - stores
      operationId: update_store
      parameters:
        - name: storeId
          in: path
          required: true
          schema:
            type: integer
          description: Unique identifier for the store
          example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                storeId:
                  type: integer
                  example: 12345
                storeName:
                  type: string
                  example: WooCommerce Store
                marketplaceId:
                  type: integer
                  example: 36
                marketplaceName:
                  type: string
                  example: WooCommerce
                integrationUrl:
                  anyOf:
                    - type: string
                    - type: 'null'
                  example: http://shipstation-test.wpengine.com
                active:
                  type: boolean
                  example: true
                companyName:
                  type: string
                  example: ''
                phone:
                  type: string
                  example: ''
                publicEmail:
                  type: string
                  example: ''
                website:
                  type: string
                  example: ''
                autoRefresh:
                  type: boolean
                  example: true
                statusMappings:
                  type: array
                  items:
                    type: object
                    properties:
                      orderStatus:
                        type: string
                        example: awaiting_shipment
                      statusKey:
                        type: string
                        example: Processing
      responses:
        '200':
          description: Store updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  storeId:
                    type: integer
                  storeName:
                    type: string
                  marketplaceId:
                    type: integer
                  marketplaceName:
                    type: string
                  active:
                    type: boolean
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
  /stores/deactivate:
    post:
      summary: Deactivate store
      description: Deactivates the specified store
      tags:
        - stores
      operationId: deactivate_store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - storeId
              properties:
                storeId:
                  type: integer
                  description: ID of the store to deactivate
                  example: 12345
      responses:
        '200':
          description: Store deactivated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Store deactivated successfully
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /stores/reactivate:
    post:
      summary: Reactivate store
      description: |
        Reactivates the specified store.

        **Note:** Stores are active by default.
      tags:
        - stores
      operationId: reactivate_store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - storeId
              properties:
                storeId:
                  type: integer
                  description: ID of the store to reactivate
                  example: 12345
      responses:
        '200':
          description: Store reactivated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Store reactivated successfully
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /stores/refreshstore:
    post:
      summary: Refresh store
      description: >
        Initiates a store refresh. If storeId is not specified, a store refresh
        will be initiated for all refreshable stores on that account.
      tags:
        - stores
      operationId: refresh_store
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                storeId:
                  type: integer
                  description: Store that will get refreshed (optional)
                  example: 12345
                refreshDate:
                  type: string
                  format: date-time
                  description: >
                    Starting date for new order imports (YYYY-MM-DD HH:MM:SS in
                    PST). This is only needed if retrieving historical orders.
                  example: '2020-05-29T15:05:02Z'
      responses:
        '200':
          description: Store refresh initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Store refresh initiated
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /stores/getrefreshstatus:
    get:
      summary: Get store refresh status
      description: Retrieves the refresh status of a given store
      tags:
        - stores
      operationId: get_store_refresh_status
      parameters:
        - name: storeId
          in: query
          required: true
          schema:
            type: integer
          description: Store whose status will be retrieved
          example: 12345
      responses:
        '200':
          description: Store refresh status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  storeId:
                    type: integer
                    example: 12345
                  refreshDate:
                    type: string
                    format: date-time
                  status:
                    type: string
                    example: Success
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /stores/marketplaces:
    get:
      summary: List marketplaces
      description: Lists the marketplaces that can be integrated with ShipStation
      tags:
        - stores
      operationId: list_marketplaces
      responses:
        '200':
          description: List of marketplaces retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      example: Shopify
                    marketplaceId:
                      type: integer
                      example: 36
                    canRefresh:
                      type: boolean
                      example: true
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /warehouses:
    get:
      summary: List warehouses
      description: >
        Retrieves a list of your Ship From Locations (formerly known as
        warehouses).


        **Note:** In the API, the endpoint is called warehouse, but the process
        actually affects Ship From Locations in the UI.
      tags:
        - warehouses
      operationId: list_warehouses
      responses:
        '200':
          description: List of warehouses retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    warehouseId:
                      type: integer
                      example: 12345
                    warehouseName:
                      type: string
                      example: Headquarters
                    originAddress:
                      $ref: '#/components/schemas/Address'
                    returnAddress:
                      anyOf:
                        - $ref: '#/components/schemas/Address'
                        - type: 'null'
                    isDefault:
                      type: boolean
                      example: true
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /warehouses/{warehouseId}:
    get:
      summary: Get warehouse
      description: >
        Returns a specific Ship From Location (formerly known as warehouse).


        **Note:** In the API, the endpoint is called warehouse, but the process
        actually affects Ship From Locations in the UI.
      tags:
        - warehouses
      operationId: get_warehouse
      parameters:
        - name: warehouseId
          in: path
          required: true
          schema:
            type: integer
          description: Warehouse ID
          example: 12345
      responses:
        '200':
          description: Warehouse retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  warehouseId:
                    type: integer
                    example: 12345
                  warehouseName:
                    type: string
                    example: Headquarters
                  originAddress:
                    $ref: '#/components/schemas/Address'
                  returnAddress:
                    anyOf:
                      - $ref: '#/components/schemas/Address'
                      - type: 'null'
                  isDefault:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
    delete:
      summary: Delete warehouse
      description: >
        Removes a warehouse from ShipStation's UI and sets it to Inactive
        status. This is a "soft" delete action.


        **Note:** In the API, the endpoint is called warehouse, but the process
        actually affects Ship From Locations in the UI.
      tags:
        - warehouses
      operationId: delete_warehouse
      parameters:
        - name: warehouseId
          in: path
          required: true
          schema:
            type: integer
          description: Warehouse ID to delete
          example: 12345
      responses:
        '200':
          description: Warehouse deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: The requested warehouse has been deleted.
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
  /warehouses/createwarehouse:
    post:
      summary: Create warehouse
      description: >
        Adds a Ship From Location (formerly known as warehouse) to your account.


        **Note:** In the API, the endpoint is called warehouse, but the process
        actually affects Ship From Locations in the UI.
      tags:
        - warehouses
      operationId: create_warehouse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - originAddress
              properties:
                warehouseName:
                  type: string
                  description: Name of Ship From Location
                  example: New Ship From Location
                originAddress:
                  $ref: '#/components/schemas/Address'
                returnAddress:
                  anyOf:
                    - $ref: '#/components/schemas/Address'
                    - type: 'null'
                isDefault:
                  type: boolean
                  description: Whether this will be the default Ship From Location
                  example: false
      responses:
        '200':
          description: Warehouse created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  warehouseId:
                    type: integer
                    example: 12345
                  warehouseName:
                    type: string
                  originAddress:
                    $ref: '#/components/schemas/Address'
                  returnAddress:
                    anyOf:
                      - $ref: '#/components/schemas/Address'
                      - type: 'null'
                  isDefault:
                    type: boolean
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /warehouses/updatewarehouse:
    put:
      summary: Update warehouse
      description: >
        Updates an existing Ship From Location (formerly known as warehouse).


        **Note:** In the API, the endpoint is called warehouse, but the process
        actually affects Ship From Locations in the UI.
      tags:
        - warehouses
      operationId: update_warehouse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - warehouseId
                - originAddress
              properties:
                warehouseId:
                  type: integer
                  description: Unique identifier for the warehouse
                  example: 17977
                warehouseName:
                  type: string
                  description: Name of Ship From Location
                  example: Flagship Location
                originAddress:
                  $ref: '#/components/schemas/Address'
                returnAddress:
                  anyOf:
                    - $ref: '#/components/schemas/Address'
                    - type: 'null'
                isDefault:
                  type: boolean
                  description: Whether this will be the default Ship From Location
                  example: true
      responses:
        '200':
          description: Warehouse updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  warehouseId:
                    type: integer
                  warehouseName:
                    type: string
                  originAddress:
                    $ref: '#/components/schemas/Address'
                  returnAddress:
                    anyOf:
                      - $ref: '#/components/schemas/Address'
                      - type: 'null'
                  isDefault:
                    type: boolean
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
  /products:
    get:
      summary: List products
      description: Obtains a list of products that match the specified criteria
      tags:
        - products
      operationId: list_products
      parameters:
        - name: sku
          in: query
          schema:
            type: string
          description: Returns products that match the specified SKU
        - name: name
          in: query
          schema:
            type: string
          description: Returns products that match the specified product name
        - name: productCategoryId
          in: query
          schema:
            type: integer
          description: Returns products that match the specified productCategoryId
        - name: productTypeId
          in: query
          schema:
            type: integer
          description: Returns products that match the specified productTypeId
        - name: tagId
          in: query
          schema:
            type: integer
          description: Returns products that match the specified tagId
        - name: startDate
          in: query
          schema:
            type: string
            format: date-time
          description: Returns products created after the specified date
        - name: endDate
          in: query
          schema:
            type: string
            format: date-time
          description: Returns products created before the specified date
        - name: showInactive
          in: query
          schema:
            type: boolean
          description: Specifies whether to include inactive products
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - SKU
              - ModifyDate
              - CreateDate
          description: Sorts the order of the response
        - $ref: '#/components/parameters/sort_dir_param'
        - $ref: '#/components/parameters/page_param'
        - $ref: '#/components/parameters/page_size_param'
      responses:
        '200':
          description: List of products retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      type: object
                      properties:
                        productId:
                          type: integer
                          example: 123456789
                        sku:
                          type: string
                          example: BEAU-000
                        name:
                          type: string
                          example: Beautiful
                        price:
                          type: number
                          example: 0
                        active:
                          type: boolean
                          example: true
                  total:
                    type: integer
                  page:
                    type: integer
                  pages:
                    type: integer
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /products/{productId}:
    get:
      summary: Get product
      description: Retrieves a single product by its ID
      tags:
        - products
      operationId: get_product
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: integer
          description: The system-generated identifier for the Product
          example: 123456789
      responses:
        '200':
          description: Product retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  productId:
                    type: integer
                    example: 123456789
                  sku:
                    type: string
                    example: BEAU-000
                  name:
                    type: string
                    example: Beautiful
                  price:
                    type: number
                    example: 0
                  active:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
    put:
      summary: Update product
      description: >
        Updates an existing product. This call does not currently support
        partial updates. The entire resource must be provided in the body of the
        request.
      tags:
        - products
      operationId: update_product
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: integer
          description: The system-generated identifier for the Product
          example: 123456789
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                productId:
                  type: integer
                  example: 123456789
                sku:
                  type: string
                  example: BEAU-000
                name:
                  type: string
                  example: Beautiful
                price:
                  type: number
                  example: 0
                active:
                  type: boolean
                  example: true
                weightOz:
                  anyOf:
                    - type: number
                    - type: 'null'
                defaultCarrierCode:
                  anyOf:
                    - type: string
                    - type: 'null'
                defaultServiceCode:
                  anyOf:
                    - type: string
                    - type: 'null'
      responses:
        '200':
          description: Product updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  productId:
                    type: integer
                  sku:
                    type: string
                  name:
                    type: string
                  active:
                    type: boolean
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
  /customers:
    get:
      summary: List customers
      description: Obtains a list of customers that match the specified criteria
      tags:
        - customers
      operationId: list_customers
      parameters:
        - name: stateCode
          in: query
          schema:
            type: string
          description: Returns customers that reside in the specified stateCode
        - name: countryCode
          in: query
          schema:
            type: string
          description: >-
            Returns customers that reside in the specified countryCode
            (two-letter ISO)
        - name: marketplaceId
          in: query
          schema:
            type: integer
          description: Returns customers that purchased from the specified marketplaceId
        - name: tagId
          in: query
          schema:
            type: integer
          description: Returns customers that have been tagged with the specified tagId
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - Name
              - ModifyDate
              - CreateDate
          description: Sorts the order of the response
        - $ref: '#/components/parameters/sort_dir_param'
        - $ref: '#/components/parameters/page_param'
        - $ref: '#/components/parameters/page_size_param'
      responses:
        '200':
          description: List of customers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      type: object
                      properties:
                        customerId:
                          type: integer
                          example: 12345678
                        name:
                          type: string
                          example: Cam Newton
                        company:
                          type: string
                          example: Test Company
                        email:
                          type: string
                          example: supermancam@example.com
                        phone:
                          type: string
                          example: 555-555-5555
                        city:
                          type: string
                          example: Auburn
                        state:
                          type: string
                          example: AL
                        countryCode:
                          type: string
                          example: US
                  total:
                    type: integer
                  page:
                    type: integer
                  pages:
                    type: integer
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /customers/{customerId}:
    get:
      summary: Get customer
      description: Retrieves a single customer by ID
      tags:
        - customers
      operationId: get_customer
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: The system-generated identifier for the Customer
          example: 12345678
      responses:
        '200':
          description: Customer retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerId:
                    type: integer
                    example: 12345678
                  name:
                    type: string
                    example: Cam Newton
                  company:
                    type: string
                    example: Test Company
                  street1:
                    type: string
                    example: 123 War Eagle Lane
                  city:
                    type: string
                    example: Auburn
                  state:
                    type: string
                    example: AL
                  postalCode:
                    type: string
                    example: '36830'
                  countryCode:
                    type: string
                    example: US
                  phone:
                    type: string
                    example: 555-555-5555
                  email:
                    type: string
                    example: supermancam@example.com
                  addressVerified:
                    type: string
                    example: Verified
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
  /users:
    get:
      summary: List users
      description: Retrieves a list of users for the account
      tags:
        - users
      operationId: list_users
      parameters:
        - name: showInactive
          in: query
          schema:
            type: boolean
          description: Determines whether or not inactive users will be returned
          example: false
      responses:
        '200':
          description: List of users retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    userId:
                      type: string
                      example: 123456AB-ab12-3c4d-5e67-89f1abc1defa
                    userName:
                      type: string
                      example: john.doe
                    name:
                      type: string
                      example: John Doe
                    email:
                      type: string
                      example: john.doe@example.com
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /fulfillments:
    get:
      summary: List fulfillments
      description: >
        Obtains a list of fulfillments that match the specified criteria.


        **Note:** Orders that have been marked as shipped either through the UI
        or API will appear in the response as they are considered fulfillments.
      tags:
        - fulfillments
      operationId: list_fulfillments
      parameters:
        - name: fulfillmentId
          in: query
          schema:
            type: integer
          description: Returns the fulfillment with the specified fulfillment ID
        - name: orderId
          in: query
          schema:
            type: integer
          description: Returns fulfillments whose orders have the specified order ID
        - name: orderNumber
          in: query
          schema:
            type: string
          description: Returns fulfillments whose orders have the specified order number
        - name: trackingNumber
          in: query
          schema:
            type: string
          description: Returns fulfillments with the specified tracking number
        - name: recipientName
          in: query
          schema:
            type: string
          description: Returns fulfillments shipped to the specified recipient name
        - name: createDateStart
          in: query
          schema:
            type: string
            format: date-time
          description: Returns fulfillments created on or after the specified date
        - name: createDateEnd
          in: query
          schema:
            type: string
            format: date-time
          description: Returns fulfillments created on or before the specified date
        - name: shipDateStart
          in: query
          schema:
            type: string
            format: date
          description: Returns fulfillments with shipDate on or after the specified date
        - name: shipDateEnd
          in: query
          schema:
            type: string
            format: date
          description: Returns fulfillments with shipDate on or before the specified date
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - ShipDate
              - CreateDate
          description: Sort the responses by a set value
        - $ref: '#/components/parameters/sort_dir_param'
        - $ref: '#/components/parameters/page_param'
        - $ref: '#/components/parameters/page_size_param'
      responses:
        '200':
          description: List of fulfillments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  fulfillments:
                    type: array
                    items:
                      type: object
                      properties:
                        fulfillmentId:
                          type: integer
                        orderId:
                          type: integer
                        orderNumber:
                          type: string
                        trackingNumber:
                          type: string
                        shipDate:
                          type: string
                          format: date
                        carrierCode:
                          type: string
                        serviceCode:
                          type: string
                  total:
                    type: integer
                  page:
                    type: integer
                  pages:
                    type: integer
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /webhooks:
    get:
      summary: List webhooks
      description: Retrieves a list of registered webhooks for the account
      tags:
        - webhooks
      operationId: list_webhooks
      responses:
        '200':
          description: List of webhooks retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      type: object
                      properties:
                        WebHookID:
                          type: integer
                          example: 123456
                        SellerID:
                          type: integer
                        StoreID:
                          anyOf:
                            - type: integer
                            - type: 'null'
                          example: 12345
                        HookType:
                          type: string
                          example: ORDER_NOTIFY
                        MessageFormat:
                          type: string
                        Url:
                          type: string
                          example: http://example.com/webhook
                        Name:
                          type: string
                          example: My Webhook
                        BulkCopyBatchID:
                          anyOf:
                            - type: integer
                            - type: 'null'
                          example: null
                        BulkCopyRecordID:
                          anyOf:
                            - type: integer
                            - type: 'null'
                          example: null
                        Active:
                          type: boolean
                        WebHookLogs:
                          type: array
                          items:
                            type: object
                        Seller:
                          anyOf:
                            - type: object
                            - type: 'null'
                        Store:
                          anyOf:
                            - type: object
                            - type: 'null'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /webhooks/subscribe:
    post:
      summary: Subscribe to webhook
      description: >
        Subscribes to a specific type of webhook. If a store_id is passed in,
        the webhooks will only be triggered for that specific store_id.


        **Note:** Webhooks can only be modified through the ShipStation UI under
        Account Settings.
      tags:
        - webhooks
      operationId: subscribe_webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - target_url
                - event
              properties:
                target_url:
                  type: string
                  description: The URL to send the webhooks to
                  example: http://someexamplewebhookurl.com/neworder
                event:
                  type: string
                  enum:
                    - ORDER_NOTIFY
                    - ITEM_ORDER_NOTIFY
                    - SHIP_NOTIFY
                    - ITEM_SHIP_NOTIFY
                    - FULFILLMENT_SHIPPED
                    - FULFILLMENT_REJECTED
                  description: The type of webhook to subscribe to
                  example: ORDER_NOTIFY
                store_id:
                  anyOf:
                    - type: integer
                    - type: 'null'
                  description: >-
                    Store ID (optional - webhooks will only trigger for this
                    store)
                  example: 12345
                friendly_name:
                  type: string
                  description: Display name for the webhook
                  example: My Webhook
      responses:
        '200':
          description: Webhook subscription created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  WebHookID:
                    type: integer
                    example: 123456
                  HookType:
                    type: string
                  Url:
                    type: string
                  Name:
                    type: string
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
  /webhooks/{webhookId}:
    delete:
      summary: Unsubscribe from webhook
      description: Unsubscribes from a certain webhook
      tags:
        - webhooks
      operationId: unsubscribe_webhook
      parameters:
        - name: webhookId
          in: path
          required: true
          schema:
            type: integer
          description: A unique ID generated by ShipStation and assigned to each webhook
          example: 123456
      responses:
        '200':
          description: Webhook unsubscribed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Webhook deleted successfully
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '500':
          $ref: '#/components/responses/server_error'
  /accounts/listtags:
    get:
      summary: List account tags
      description: List all tags defined for this account
      tags:
        - accounts
      operationId: list_account_tags
      responses:
        '200':
          description: List of tags retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    tagId:
                      type: integer
                      example: 8362
                    name:
                      type: string
                      example: Backorder
                    color:
                      type: string
                      example: '#800080'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/server_error'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using ShipStation API Key and Secret
  parameters:
    page_param:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number
    page_size_param:
      name: pageSize
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
      description: Number of results per page. Maximum 500.
    sort_by_param:
      name: sortBy
      in: query
      schema:
        type: string
        enum:
          - OrderDate
          - ModifyDate
          - CreateDate
      description: Field to sort results by
    sort_dir_param:
      name: sortDir
      in: query
      schema:
        type: string
        enum:
          - ASC
          - DESC
        default: ASC
      description: Sort direction
  responses:
    bad_request:
      description: >-
        Bad Request - The request could not be understood or was missing
        required parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Invalid request parameters
    unauthorized:
      description: Unauthorized - Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Invalid API credentials
    not_found:
      description: Not Found - The specified resource was not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Resource not found
    server_error:
      description: Internal Server Error - An error occurred on the server
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: An internal error occurred
  schemas:
    Address:
      type: object
      description: Physical address for shipping or billing
      properties:
        name:
          type: string
          description: Name of the recipient
          example: John Doe
        company:
          anyOf:
            - type: string
            - type: 'null'
          description: Company name
          example: Acme Corp
        street1:
          type: string
          description: First line of the street address
          example: 123 Main St
        street2:
          anyOf:
            - type: string
            - type: 'null'
          description: Second line of the street address
          example: Apt 4B
        street3:
          anyOf:
            - type: string
            - type: 'null'
          description: Third line of the street address
          example: Building B
        city:
          type: string
          description: City name
          example: Austin
        state:
          type: string
          description: State or province code
          example: TX
        postalCode:
          type: string
          description: Postal or ZIP code
          example: '78701'
        country:
          type: string
          description: Two-letter ISO country code
          example: US
        phone:
          anyOf:
            - type: string
            - type: 'null'
          description: Phone number
          example: 512-555-1234
        residential:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Whether the address is residential
          example: true
        addressVerified:
          anyOf:
            - type: string
            - type: 'null'
          description: Address verification status
          example: Address validated successfully
    Weight:
      type: object
      description: Weight measurement
      required:
        - value
        - units
      properties:
        value:
          type: number
          description: Weight value
          example: 24
        units:
          type: string
          enum:
            - pounds
            - ounces
            - grams
          description: Weight unit of measurement
          example: ounces
    Dimensions:
      type: object
      description: Package dimensions
      required:
        - length
        - width
        - height
        - units
      properties:
        length:
          type: number
          description: Length
          example: 7
        width:
          type: number
          description: Width
          example: 5
        height:
          type: number
          description: Height
          example: 6
        units:
          type: string
          enum:
            - inches
            - centimeters
          description: Dimension unit of measurement
          example: inches
    InsuranceOptions:
      type: object
      description: Shipping insurance options
      properties:
        provider:
          anyOf:
            - type: string
            - type: 'null'
          enum:
            - none
            - carrier
            - shipsurance
          description: Insurance provider
          example: carrier
        insureShipment:
          type: boolean
          description: Whether to insure the shipment
          example: true
        insuredValue:
          type: number
          description: Insured value amount
          example: 200
    InternationalOptions:
      type: object
      description: International shipping options
      properties:
        contents:
          anyOf:
            - type: string
            - type: 'null'
          enum:
            - merchandise
            - documents
            - gift
            - returned_goods
            - sample
          description: Type of contents
          example: merchandise
        customsItems:
          anyOf:
            - type: array
            - type: 'null'
          items:
            $ref: '#/components/schemas/CustomsItem'
          description: Array of customs items
        nonDelivery:
          anyOf:
            - type: string
            - type: 'null'
          enum:
            - return_to_sender
            - treat_as_abandoned
          description: Action to take if delivery fails
          example: return_to_sender
    CustomsItem:
      type: object
      description: Customs item for international shipments
      properties:
        customsItemId:
          type: integer
          description: System-generated customs item ID
          example: 11558268
        description:
          type: string
          description: Item description
          example: Cotton T-Shirt
        quantity:
          type: integer
          description: Quantity
          example: 2
        value:
          type: number
          description: Item value
          example: 49.99
        harmonizedTariffCode:
          anyOf:
            - type: string
            - type: 'null'
          description: Harmonized tariff code
          example: 6109.10.0012
        countryOfOrigin:
          type: string
          description: Two-letter ISO country code
          example: US
    AdvancedOptions:
      type: object
      description: Advanced shipping options
      properties:
        warehouseId:
          anyOf:
            - type: integer
            - type: 'null'
          description: Warehouse ID
          example: 98765
        nonMachinable:
          type: boolean
          description: Whether the package is non-machinable
          example: false
        saturdayDelivery:
          type: boolean
          description: Whether to deliver on Saturday
          example: false
        containsAlcohol:
          type: boolean
          description: Whether the package contains alcohol
          example: false
        mergedOrSplit:
          type: boolean
          description: Whether this is a merged or split order
          example: false
        mergedIds:
          type: array
          items:
            type: integer
          description: Array of merged order IDs
        parentId:
          anyOf:
            - type: integer
            - type: 'null'
          description: Parent order ID for split orders
          example: 93348442
        storeId:
          anyOf:
            - type: integer
            - type: 'null'
          description: Store ID
          example: 12345
        customField1:
          anyOf:
            - type: string
            - type: 'null'
          description: Custom field 1
          example: Custom data that you can add to an order
        customField2:
          anyOf:
            - type: string
            - type: 'null'
          description: Custom field 2
          example: Per UI settings, this can appear on some carrier labels
        customField3:
          anyOf:
            - type: string
            - type: 'null'
          description: Custom field 3
          example: https://help.shipstation.com/hc/en-us/articles/206639957
        source:
          anyOf:
            - type: string
            - type: 'null'
          description: Order source
          example: Webstore
        billToParty:
          anyOf:
            - type: string
            - type: 'null'
          description: Bill to party
          example: third_party
        billToAccount:
          anyOf:
            - type: string
            - type: 'null'
          description: Bill to account
          example: '123456789'
        billToPostalCode:
          anyOf:
            - type: string
            - type: 'null'
          description: Bill to postal code
          example: '78701'
        billToCountryCode:
          anyOf:
            - type: string
            - type: 'null'
          description: Bill to country code
          example: US
    OrderItem:
      type: object
      description: Item in an order
      properties:
        orderItemId:
          type: integer
          readOnly: true
          description: System-generated order item ID
          example: 128836912
        lineItemKey:
          anyOf:
            - type: string
            - type: 'null'
          description: External line item key
          example: vd08-MSLbtx
        sku:
          type: string
          description: Product SKU
          example: ABC123
        name:
          type: string
          description: Item name
          example: 'Test item #1'
        imageUrl:
          anyOf:
            - type: string
            - type: 'null'
          description: Item image URL
          example: https://example.com/images/product.jpg
        weight:
          $ref: '#/components/schemas/Weight'
        quantity:
          type: integer
          description: Quantity
          example: 2
        unitPrice:
          type: number
          description: Unit price
          example: 99.99
        taxAmount:
          anyOf:
            - type: number
            - type: 'null'
          description: Tax amount
          example: 2.5
        shippingAmount:
          anyOf:
            - type: number
            - type: 'null'
          description: Shipping amount
          example: 5
        warehouseLocation:
          anyOf:
            - type: string
            - type: 'null'
          description: Warehouse location
          example: Aisle 1, Bin 7
        options:
          type: array
          items:
            $ref: '#/components/schemas/ItemOption'
          description: Item options
        productId:
          anyOf:
            - type: integer
            - type: 'null'
          description: Product ID
          example: 7239919
        fulfillmentSku:
          anyOf:
            - type: string
            - type: 'null'
          description: Fulfillment SKU
          example: SKU-Fulfilled
        adjustment:
          type: boolean
          description: Whether this is an adjustment item
          example: false
        upc:
          anyOf:
            - type: string
            - type: 'null'
          description: UPC code
          example: 32-65-98
        createDate:
          type: string
          format: date-time
          readOnly: true
          description: Creation timestamp
        modifyDate:
          type: string
          format: date-time
          readOnly: true
          description: Last modification timestamp
    ItemOption:
      type: object
      description: Item option/variant
      properties:
        name:
          type: string
          description: Option name
          example: Size
        value:
          type: string
          description: Option value
          example: Large
    Order:
      type: object
      description: Complete order object
      properties:
        orderId:
          type: integer
          readOnly: true
          description: System-generated identifier for the order
          example: 93348442
        orderNumber:
          type: string
          description: User-defined order number
          example: TEST-ORDER-API-DOCS
        orderKey:
          type: string
          description: Unique key for the order
          example: 0f6bec18-3e89-4771-83aa-f392d84f4c74
        orderDate:
          type: string
          format: date-time
          description: Date the order was placed
          example: '2015-06-29T08:46:27Z'
        createDate:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when order was created in ShipStation
          example: '2016-01-12T16:03:06Z'
        modifyDate:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when order was last modified
          example: '2016-01-12T16:03:06Z'
        paymentDate:
          anyOf:
            - type: string
            - type: 'null'
          format: date-time
          description: Date the order was paid
          example: '2015-06-29T08:46:27Z'
        shipByDate:
          anyOf:
            - type: string
            - type: 'null'
          format: date-time
          description: Date the order should be shipped by
          example: '2015-07-05T00:00:00Z'
        orderStatus:
          type: string
          enum:
            - awaiting_payment
            - awaiting_shipment
            - pending_fulfillment
            - shipped
            - on_hold
            - cancelled
            - rejected_fulfillment
          description: Current status of the order
          example: awaiting_shipment
        customerId:
          type: integer
          readOnly: true
          description: Unique identifier for the customer
          example: 37701499
        customerUsername:
          type: string
          description: Customer username or identifier
          example: headhoncho@whitehouse.gov
        customerEmail:
          type: string
          format: email
          description: Customer email address
          example: headhoncho@whitehouse.gov
        billTo:
          $ref: '#/components/schemas/Address'
        shipTo:
          $ref: '#/components/schemas/Address'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
          description: Array of order items
        orderTotal:
          type: number
          readOnly: true
          description: Total order amount
          example: 194.43
        amountPaid:
          type: number
          description: Amount paid by customer
          example: 218.73
        taxAmount:
          type: number
          description: Total tax amount
          example: 5
        shippingAmount:
          type: number
          description: Shipping amount
          example: 10
        customerNotes:
          anyOf:
            - type: string
            - type: 'null'
          description: Notes from the customer
          example: Please ship as soon as possible!
        internalNotes:
          anyOf:
            - type: string
            - type: 'null'
          description: Internal notes (not visible to customer)
          example: Customer called and would like to upgrade shipping
        gift:
          type: boolean
          description: Whether this is a gift order
          example: false
        giftMessage:
          anyOf:
            - type: string
            - type: 'null'
          description: Gift message
          example: Happy Birthday!
        paymentMethod:
          anyOf:
            - type: string
            - type: 'null'
          description: Payment method used
          example: Credit Card
        requestedShippingService:
          anyOf:
            - type: string
            - type: 'null'
          description: Shipping service requested by customer
          example: Priority Mail
        carrierCode:
          anyOf:
            - type: string
            - type: 'null'
          description: Carrier code
          example: fedex
        serviceCode:
          anyOf:
            - type: string
            - type: 'null'
          description: Service code
          example: fedex_2day
        packageCode:
          anyOf:
            - type: string
            - type: 'null'
          description: Package type code
          example: package
        confirmation:
          type: string
          enum:
            - none
            - delivery
            - signature
            - adult_signature
            - direct_signature
          description: Delivery confirmation type
          example: none
        shipDate:
          anyOf:
            - type: string
            - type: 'null'
          format: date
          description: Date the order was shipped
          example: '2015-07-02'
        holdUntilDate:
          anyOf:
            - type: string
            - type: 'null'
          format: date
          description: Date to hold order until
          example: '2015-07-05'
        weight:
          $ref: '#/components/schemas/Weight'
        dimensions:
          anyOf:
            - $ref: '#/components/schemas/Dimensions'
            - type: 'null'
        insuranceOptions:
          $ref: '#/components/schemas/InsuranceOptions'
        internationalOptions:
          $ref: '#/components/schemas/InternationalOptions'
        advancedOptions:
          $ref: '#/components/schemas/AdvancedOptions'
        tagIds:
          anyOf:
            - type: array
            - type: 'null'
          items:
            type: integer
          description: Array of tag IDs associated with this order
        userId:
          anyOf:
            - type: string
            - type: 'null'
          readOnly: true
          description: User assigned to order (GUID format)
          example: 123456AB-ab12-3c4d-5e67-89f1abc1defa
        externallyFulfilled:
          type: boolean
          readOnly: true
          description: Whether order is externally fulfilled
          example: false
        externallyFulfilledBy:
          anyOf:
            - type: string
            - type: 'null'
          readOnly: true
          description: External fulfillment provider name
          example: Amazon FBA
security:
  - basicAuth: []
