openapi: 3.0.3
info:
  title: 3PL Warehouse Manager (SecureWMS) REST API
  description: >-
    REST API for 3PL Warehouse Manager, the cloud warehouse management system
    (WMS) for third-party logistics providers, sold under Extensiv and
    historically known as "3PL Central". The public integration surface is the
    SecureWMS REST API served from https://secure-wms.com. It is used to create
    and retrieve orders, manage SKU items and inventory, read stock summaries and
    stock details, submit and track inbound receivers (Advance Ship Notices),
    and enumerate customers, warehouses/facilities, and locations.


    Authentication is OAuth 2.0 client-credentials. Base64-encode
    "clientId:clientSecret" and POST it as a Basic Authorization header to
    /AuthServer/api/Token with a JSON body of
    {"grant_type":"client_credentials","user_login_id":<id>} (a user_login or
    user_login_id provided by the warehouse for auditing). The returned bearer
    access token is short-lived - typically valid 30 to 60 minutes - and should
    be refreshed at least every 30 minutes. All traffic must use HTTPS; plain
    HTTP is not supported.


    Collection endpoints are paged with pgnum (page number) and pgsiz (page
    size) query parameters and can be filtered with Resource Query Language
    (RQL, http://api.3plcentral.com/rels/rql) via the rql parameter and ordered
    with sort. Responses are HAL-style JSON where list payloads carry records
    under a ResourceList (or Summaries for stock summaries) property.


    Endpoint provenance: read (GET) endpoints for customers, items, inventory,
    stock details, stock summaries, facility locations, and orders are CONFIRMED
    against the public developer portal and the open-source singer-io
    tap-3plcentral extractor. Order creation, receiver (ASN) create/list/get,
    and the facilities and order-packages resources are documented in the 3PL
    Warehouse Manager developer portal; request/response shapes that are gated
    behind the authenticated developer portal are MODELED here honestly and
    marked per-operation with x-endpoint-status.
  version: '1.0'
  contact:
    name: Extensiv - 3PL Warehouse Manager Developer Community
    url: https://developer.3plcentral.com/
  license:
    name: Proprietary
    url: https://www.extensiv.com/legal
servers:
  - url: https://secure-wms.com
    description: 3PL Warehouse Manager (SecureWMS) production
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: OAuth 2.0 client-credentials token issuance.
  - name: Orders
    description: Outbound order creation and retrieval.
  - name: Items
    description: Customer SKU items (catalog).
  - name: Inventory
    description: On-hand inventory and per-receive stock details.
  - name: Stock Summaries
    description: Rolled-up on-hand / available / allocated quantities.
  - name: Receivers
    description: Inbound receivers (Advance Ship Notices).
  - name: Customers
    description: Customers (merchants) a 3PL fulfills for.
  - name: Warehouses
    description: Facilities and their bin locations.
  - name: Packages
    description: Packages (cartons) on a shipped order.
paths:
  /AuthServer/api/Token:
    post:
      operationId: getAccessToken
      tags:
        - Authentication
      summary: Issue an OAuth 2.0 access token
      description: >-
        Exchanges Base64-encoded client credentials (Basic auth header) for a
        short-lived bearer access token using the client_credentials grant.
        CONFIRMED against the Extensiv "Providing REST API Access" documentation.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: An access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers:
    get:
      operationId: listCustomers
      tags:
        - Customers
      summary: List customers
      description: >-
        Lists the customers (merchants) configured in the warehouse. Paged with
        pgnum/pgsiz, filterable with rql, sortable (e.g. ReadOnly.CreationDate).
        CONFIRMED (GET /customers).
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/pgnum'
        - $ref: '#/components/parameters/pgsiz'
        - $ref: '#/components/parameters/rql'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: A page of customers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customerId}/items:
    get:
      operationId: listCustomerItems
      tags:
        - Items
      summary: List a customer's SKU items
      description: >-
        Lists the SKU items defined for a customer. Paged/filterable/sortable
        (e.g. ReadOnly.lastModifiedDate). CONFIRMED (GET /customers/{id}/items).
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/pgnum'
        - $ref: '#/components/parameters/pgsiz'
        - $ref: '#/components/parameters/rql'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: A page of items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /inventory:
    get:
      operationId: getInventory
      tags:
        - Inventory
      summary: Retrieve on-hand inventory
      description: >-
        Retrieves inventory received on or before a point in time. Paged,
        filterable with rql, sortable by receivedDate. CONFIRMED (GET /inventory).
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/pgnum'
        - $ref: '#/components/parameters/pgsiz'
        - $ref: '#/components/parameters/rql'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: A page of inventory records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /inventory/stockdetails:
    get:
      operationId: getStockDetails
      tags:
        - Inventory
      summary: Retrieve stock details
      description: >-
        Per-receive-line stock detail records (facility, item, lot, expiration,
        received date, quantities). Paged/filterable/sortable by receivedDate.
        CONFIRMED (GET /inventory/stockdetails).
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/pgnum'
        - $ref: '#/components/parameters/pgsiz'
        - $ref: '#/components/parameters/rql'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: A page of stock detail records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /inventory/stocksummaries:
    get:
      operationId: getStockSummaries
      tags:
        - Stock Summaries
      summary: Retrieve stock summaries
      description: >-
        Rolled-up on-hand / available / allocated / committed quantities keyed
        by facility and item. List payload is carried under a Summaries property.
        CONFIRMED (GET /inventory/stocksummaries).
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/pgnum'
        - $ref: '#/components/parameters/pgsiz'
        - $ref: '#/components/parameters/rql'
      responses:
        '200':
          description: A page of stock summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummariesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /inventory/facilities:
    get:
      operationId: listFacilities
      tags:
        - Warehouses
      summary: List warehouses / facilities
      description: >-
        Lists the physical facilities (warehouses) in the account. DOCUMENTED in
        the developer portal; the facilities collection is the parent of the
        CONFIRMED /inventory/facilities/{facilityId}/locations resource. MODELED.
      x-endpoint-status: modeled
      parameters:
        - $ref: '#/components/parameters/pgnum'
        - $ref: '#/components/parameters/pgsiz'
        - $ref: '#/components/parameters/rql'
      responses:
        '200':
          description: A page of facilities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /inventory/facilities/{facilityId}/locations:
    get:
      operationId: listFacilityLocations
      tags:
        - Warehouses
      summary: List bin locations in a facility
      description: >-
        Lists the bin/pick locations within a facility. Paged/filterable.
        CONFIRMED (GET /inventory/facilities/{facilityId}/locations).
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/facilityId'
        - $ref: '#/components/parameters/pgnum'
        - $ref: '#/components/parameters/pgsiz'
        - $ref: '#/components/parameters/rql'
      responses:
        '200':
          description: A page of locations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders:
    get:
      operationId: listOrders
      tags:
        - Orders
      summary: List orders
      description: >-
        Lists outbound orders. Paged, filterable with rql, sortable by
        ReadOnly.lastModifiedDate. CONFIRMED (GET /orders).
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/pgnum'
        - $ref: '#/components/parameters/pgsiz'
        - $ref: '#/components/parameters/rql'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: A page of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOrder
      tags:
        - Orders
      summary: Create an order
      description: >-
        Creates an outbound order (customer, ship-to, line items, shipping
        instructions). Creating and retrieving orders is the most common use of
        the API. DOCUMENTED in the developer portal (POST /orders); request body
        is MODELED here.
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{orderId}:
    get:
      operationId: getOrder
      tags:
        - Orders
      summary: Retrieve an order
      description: >-
        Retrieves a single order by id. DOCUMENTED in the developer portal;
        response is MODELED here.
      x-endpoint-status: modeled
      parameters:
        - $ref: '#/components/parameters/orderId'
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /orders/{orderId}/packages:
    get:
      operationId: getOrderPackages
      tags:
        - Packages
      summary: Retrieve packages for an order
      description: >-
        Lists the packages (cartons) on a shipped order - dimensions, weight,
        tracking numbers, and contained items. Order packages are a documented
        sub-resource of an order; the standalone shape is MODELED here.
      x-endpoint-status: modeled
      parameters:
        - $ref: '#/components/parameters/orderId'
      responses:
        '200':
          description: The order's packages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /inventory/receivers:
    get:
      operationId: listReceivers
      tags:
        - Receivers
      summary: List receivers (ASN)
      description: >-
        Lists inbound receivers (Advance Ship Notices). A receiver can be looked
        up by tracking/reference number via rql. DOCUMENTED (GET
        /inventory/receivers); response is MODELED here.
      x-endpoint-status: modeled
      parameters:
        - $ref: '#/components/parameters/pgnum'
        - $ref: '#/components/parameters/pgsiz'
        - $ref: '#/components/parameters/rql'
      responses:
        '200':
          description: A page of receivers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createReceiver
      tags:
        - Receivers
      summary: Create a receiver (ASN)
      description: >-
        Creates an inbound receiver (Advance Ship Notice) the warehouse will
        receive goods against. DOCUMENTED (POST /inventory/receivers); request
        body is MODELED here.
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiverCreate'
      responses:
        '201':
          description: The created receiver.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receiver'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /inventory/receivers/{receiverId}:
    get:
      operationId: getReceiver
      tags:
        - Receivers
      summary: Retrieve a receiver (ASN)
      description: >-
        Retrieves a single inbound receiver by id. DOCUMENTED (GET
        /inventory/receivers/{id}); response is MODELED here.
      x-endpoint-status: modeled
      parameters:
        - $ref: '#/components/parameters/receiverId'
      responses:
        '200':
          description: The receiver.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receiver'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived access token from POST /AuthServer/api/Token.
    basicAuth:
      type: http
      scheme: basic
      description: Base64-encoded "clientId:clientSecret" used only to obtain a token.
  parameters:
    pgnum:
      name: pgnum
      in: query
      description: Page number (1-based).
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    pgsiz:
      name: pgsiz
      in: query
      description: Page size (records per page).
      required: false
      schema:
        type: integer
        minimum: 1
        default: 100
    rql:
      name: rql
      in: query
      description: >-
        Resource Query Language filter, e.g. "readonly.lastModifiedDate=ge=2024-01-01".
        Reference http://api.3plcentral.com/rels/rql.
      required: false
      schema:
        type: string
    sort:
      name: sort
      in: query
      description: Field to sort by, e.g. ReadOnly.lastModifiedDate or receivedDate.
      required: false
      schema:
        type: string
    customerId:
      name: customerId
      in: path
      required: true
      description: The customer identifier.
      schema:
        type: integer
    facilityId:
      name: facilityId
      in: path
      required: true
      description: The facility (warehouse) identifier.
      schema:
        type: integer
    orderId:
      name: orderId
      in: path
      required: true
      description: The order identifier.
      schema:
        type: integer
    receiverId:
      name: receiverId
      in: path
      required: true
      description: The receiver (ASN) identifier.
      schema:
        type: integer
  schemas:
    TokenRequest:
      type: object
      required:
        - grant_type
      properties:
        grant_type:
          type: string
          example: client_credentials
        user_login_id:
          type: integer
          description: User login id provided by the warehouse, used for auditing.
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Token lifetime in seconds (typically 1800-3600).
    ResourceListResponse:
      type: object
      description: HAL-style list payload. Records are carried under ResourceList.
      properties:
        TotalResults:
          type: integer
        ResourceList:
          type: array
          items:
            type: object
            additionalProperties: true
        _links:
          type: object
          additionalProperties: true
    SummariesResponse:
      type: object
      description: Stock summaries list payload. Records are carried under Summaries.
      properties:
        TotalResults:
          type: integer
        Summaries:
          type: array
          items:
            $ref: '#/components/schemas/StockSummary'
        _links:
          type: object
          additionalProperties: true
    StockSummary:
      type: object
      properties:
        FacilityId:
          type: integer
        ItemId:
          type: integer
        Sku:
          type: string
        OnHand:
          type: number
        Available:
          type: number
        Allocated:
          type: number
        Committed:
          type: number
    OrderCreate:
      type: object
      required:
        - CustomerIdentifier
        - OrderItems
      properties:
        CustomerIdentifier:
          $ref: '#/components/schemas/CustomerIdentifier'
        FacilityIdentifier:
          $ref: '#/components/schemas/FacilityIdentifier'
        ReferenceNum:
          type: string
        PoNum:
          type: string
        ShipTo:
          $ref: '#/components/schemas/Address'
        OrderItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    Order:
      allOf:
        - $ref: '#/components/schemas/OrderCreate'
        - type: object
          properties:
            OrderId:
              type: integer
            ReadOnly:
              type: object
              additionalProperties: true
    OrderItem:
      type: object
      properties:
        ItemIdentifier:
          $ref: '#/components/schemas/ItemIdentifier'
        Qty:
          type: number
        SecondaryQty:
          type: number
    ReceiverCreate:
      type: object
      required:
        - CustomerIdentifier
      properties:
        CustomerIdentifier:
          $ref: '#/components/schemas/CustomerIdentifier'
        FacilityIdentifier:
          $ref: '#/components/schemas/FacilityIdentifier'
        ReferenceNum:
          type: string
        PoNum:
          type: string
        ExpectedDate:
          type: string
          format: date-time
        ReceiveItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    Receiver:
      allOf:
        - $ref: '#/components/schemas/ReceiverCreate'
        - type: object
          properties:
            ReceiverId:
              type: integer
            ReadOnly:
              type: object
              additionalProperties: true
    CustomerIdentifier:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
    FacilityIdentifier:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
    ItemIdentifier:
      type: object
      properties:
        Id:
          type: integer
        Sku:
          type: string
    Address:
      type: object
      properties:
        Name:
          type: string
        Address1:
          type: string
        Address2:
          type: string
        City:
          type: string
        State:
          type: string
        Zip:
          type: string
        Country:
          type: string
  responses:
    Unauthorized:
      description: Missing, invalid, or expired access token.
    BadRequest:
      description: The request payload failed validation.
    NotFound:
      description: The requested resource was not found.