Order Lookup by Shopify Reference

Look up the current PIMS state of an order using the Shopify order number it was created with. This endpoint is intended for external apps that need to follow an order from Shopify through its PIMS lifecycle (quote → sales order → invoice) without integrating against PIMS directly.

A single Shopify order number can map to more than one PIMS record — for example, a partial invoice for what shipped plus a remaining sales order for backordered units. The endpoint returns every matching record and reports each one's raw PIMS lifecycle stage, leaving you to interpret fulfillment state.

Endpoint

GET /tenant/api/pims/v1/orders/by_shopify_reference

Authentication

This endpoint uses the standard PIMS Open API credential pattern. Supply your tenant's API ID and API Secret in either of two ways:

• HTTP Basic Auth (recommended): Authorization: Basic <base64(apiID:apiSecret)>
• Query or body parameters: ?apiID=...&apiSecret=...

Both apiID and apiSecret are validated against your tenant's API settings on every call. A missing or mismatched credential returns 401.

Query parameters

*Either HTTP Basic Auth or the apiID + apiSecret parameters must be provided.

Response

A 200 OK returns a JSON body with the requested Shopify order number and an orders array — one entry per matching PIMS record. The array is empty when nothing matches.

{
  "shopify_order_number": "#12345",
  "orders": [
    {
      "order_type": "invoice",
      "pims_order_number": "INV5001",
      "create_date": "2026-02-25T05:00:00.000Z",
      "modified_date": "2026-03-02T05:00:00.000Z",
      "tracking_numbers": ["1Z9990001", "1Z9990002"],
      "is_dropship": false,
      "shipping_address": {
        "name": "Jane Doe",
        "attention": "",
        "address_1": "123 Main St",
        "address_2": "",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "country": "US",
        "phone": "512-555-0100"
      },
      "items": [
        {
          "part_number": "MDVQ4LL/A",
          "description": "iPhone 14 Pro",
          "quantity": 10,
          "shipped": 5,
          "serial_numbers": ["LYGX9RW917"],
          "is_applecare": false
        }
      ]
    }
  ]
}

The orders array is ordered most-progressed stage first (invoice > sales_order > quote > worksheet), then newest create_date first within each stage, with pims_order_number as the final tiebreaker.

Top-level fields

• shopify_order_number — echoes the order number you requested.
• orders — an array of matching PIMS records, empty when the Shopify order number isn't found in PIMS. Each entry is described below.

order_type values

Each order reports its raw PIMS lifecycle stage. The endpoint does not compute shipped/awaiting/backordered — you derive that yourself (see Interpreting fulfillment state).

When the Shopify order number isn't in PIMS at all, orders is an empty array and there is no order_type.

Per-order fields

• order_type — the PIMS lifecycle stage (see the table above).
• pims_order_number — the PIMS order number, or null.
• create_date / modified_date — when the PIMS order record was created and last modified, as ISO 8601 timestamps. null when PIMS has no value. create_date is the secondary sort key for the orders array.
• tracking_numbers — an array of tracking numbers for that order, returned whenever PIMS has them (typically once the order is invoiced). Tracking is recorded at the order level, not per line item.
• is_dropship — true when the order is flagged as a drop ship to the customer.
• shipping_address — the order's PIMS ship-to address. Individual fields are empty strings when PIMS has no value. Keys: name, attention, address_1, address_2, city, state, zip, country, phone.
• items — the order's line items (see below).

Item fields

Each entry in items has exactly these six fields:

• part_number — the product's part number.
• description — the product description.
• quantity — the quantity ordered on the line item.
• shipped — the quantity shipped on the line item. A shipped value lower than quantity indicates a partial shipment (for example, quantity: 10, shipped: 5).
• serial_numbers — an array of serial numbers for the line item. AppleCare items always return an empty array, because the serial belongs to the parent physical product.
• is_applecare — true when the line item is an AppleCare product.

Interpreting fulfillment state

The endpoint returns raw PIMS facts rather than a single computed status, so your app decides what "shipped", "awaiting", or "backordered" means:

• Compare each item's shipped against its quantity to detect partial shipments.
• Check tracking_numbers to see whether anything has shipped.
• Aggregate across the orders array. For example, a partial invoice plus a remaining sales_order together reconstruct "some units shipped, the rest are still backordered".

Errors

Example request

curl -s -u 'YOUR_API_ID:YOUR_API_SECRET' \
  'https://cloud.weevio.co/tenant/api/pims/v1/orders/by_shopify_reference' \
  --get \
  --data-urlencode 'teamID=<YOUR-TEAM-ID>' \
  --data-urlencode 'shopify_order_number=#12345'