Fulfillment

The Fulfillment API provides access to warehouse operations including incoming shipment alerts, inventory receiving, and outbound shipment processing. Manage your 3PL operations programmatically.

All endpoints require authentication via Bearer token with fulfillment:read or fulfillment:write scope.

GET/v1/fulfillment/warehouses

List warehouses

Returns a list of available warehouses for fulfillment operations.

Request

GET

/v1/fulfillment/warehouses

curl https://app.price2b.com/api/v1/fulfillment/warehouses \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "warehouses": [
      {
        "id": 1,
        "code": "MIAMI",
        "name": "Miami Warehouse",
        "address": {
          "address1": "123 NW 123rd St",
          "city": "Miami",
          "state": "FL",
          "postal_code": "33166",
          "country": "US"
        },
        "services": ["storage", "pick_pack", "forwarding"],
        "supported_carriers": ["fedex", "ups", "dhl"],
        "contact": {
          "email": "miami@price2b.com",
          "phone": "+1-305-555-0100"
        }
      },
      {
        "id": 2,
        "code": "LAX",
        "name": "Los Angeles Warehouse",
        "address": {
          "address1": "456 Commerce Blvd",
          "city": "Carson",
          "state": "CA",
          "postal_code": "90745",
          "country": "US"
        },
        "services": ["storage", "pick_pack", "forwarding", "returns"],
        "supported_carriers": ["fedex", "ups", "dhl", "usps"]
      }
    ]
  }
}

GET/v1/fulfillment/warehouses/:id

Get warehouse details

Retrieves detailed information about a specific warehouse including available services and rates.

Request

GET

/v1/fulfillment/warehouses/1

curl https://app.price2b.com/api/v1/fulfillment/warehouses/1 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "id": 1,
    "code": "MIAMI",
    "name": "Miami Warehouse",
    "address": {"..."},
    "services": {
      "storage": {
        "available": true,
        "rate_per_cbm_month": 25.00
      },
      "pick_pack": {
        "available": true,
        "base_rate": 2.50,
        "per_item_rate": 0.50
      },
      "forwarding": {
        "available": true
      }
    },
    "hours": {
      "receiving": "Mon-Fri 8:00 AM - 5:00 PM EST",
      "shipping": "Mon-Fri 9:00 AM - 4:00 PM EST"
    }
  }
}

GET/v1/fulfillment/incoming

List incoming shipments

Returns a list of incoming shipment alerts.

Query parameters

Name
warehouse_id
Type
integer
Description
Filter by warehouse.
Name
status
Type
string
Description
Filter by status: pending, in_transit, received, processing.
Name
date_from
Type
datetime
Description
Alerts created after this date.

Request

GET

/v1/fulfillment/incoming

curl -G https://app.price2b.com/api/v1/fulfillment/incoming \
  -H "Authorization: Bearer {token}" \
  -d warehouse_id=1 \
  -d status=pending

Response

{
  "success": true,
  "data": {
    "incoming": [
      {
        "id": 101,
        "warehouse_id": 1,
        "warehouse_name": "Miami Warehouse",
        "tracking_number": "1Z999AA10123456784",
        "carrier": "ups",
        "status": "pending",
        "expected_date": "2026-02-05",
        "shipper": {
          "name": "Amazon Fulfillment",
          "company": "Amazon.com"
        },
        "items_count": 3,
        "created_at": "2026-01-30T10:00:00Z"
      }
    ],
    "pagination": {"..."}
  }
}

POST/v1/fulfillment/incoming

Create incoming alert

Creates an incoming shipment alert to notify the warehouse of an expected delivery.

Required attributes

Name
warehouse_id
Type
integer
Description
Target warehouse ID.
Name
tracking_number
Type
string
Description
Carrier tracking number.
Name
carrier
Type
string
Description
Carrier name: ups, fedex, dhl, usps, etc.
Name
shipper
Type
object
Description
Shipper address information.
Name
items
Type
array
Description
Expected items with product_id and quantity.

Optional attributes

Name
expected_date
Type
date
Description
Expected delivery date (YYYY-MM-DD).
Name
notes
Type
string
Description
Special handling instructions.
Name
po_number
Type
string
Description
Purchase order reference.

Request

POST

/v1/fulfillment/incoming

curl -X POST https://app.price2b.com/api/v1/fulfillment/incoming \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouse_id": 1,
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups",
    "shipper": {
      "name": "Amazon Fulfillment",
      "company": "Amazon.com",
      "address1": "123 Amazon Way",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US"
    },
    "expected_date": "2026-02-05",
    "items": [
      {
        "product_id": 12345,
        "quantity": 100,
        "unit_value": 25.00
      },
      {
        "product_id": 12346,
        "quantity": 50,
        "unit_value": 35.00
      }
    ],
    "notes": "Handle with care - electronics"
  }'

Response (201)

{
  "success": true,
  "message": "Incoming alert created successfully",
  "data": {
    "id": 102,
    "warehouse_id": 1,
    "tracking_number": "1Z999AA10123456784",
    "status": "pending",
    "expected_date": "2026-02-05",
    "items_count": 2,
    "total_units": 150,
    "created_at": "2026-01-31T10:00:00Z"
  }
}

POST/v1/fulfillment/incoming/:id/receive

Receive incoming shipment

Marks an incoming shipment as received and updates inventory.

Required attributes

Name
received_items
Type
array
Description
Items actually received with quantities.

Optional attributes

Name
notes
Type
string
Description
Receiving notes (damages, discrepancies, etc.).
Name
received_by
Type
string
Description
Name of person who received the shipment.

Request

POST

/v1/fulfillment/incoming/102/receive

curl -X POST https://app.price2b.com/api/v1/fulfillment/incoming/102/receive \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "received_items": [
      {
        "product_id": 12345,
        "quantity_received": 100
      },
      {
        "product_id": 12346,
        "quantity_received": 48,
        "notes": "2 units damaged"
      }
    ],
    "notes": "Package slightly damaged, 2 items affected",
    "received_by": "John Smith"
  }'

Response

{
  "success": true,
  "message": "Shipment received and inventory updated",
  "data": {
    "incoming_id": 102,
    "status": "received",
    "received_at": "2026-02-05T14:30:00Z",
    "inventory_updates": [
      {
        "product_id": 12345,
        "sku": "PROD-001",
        "quantity_added": 100,
        "new_warehouse_quantity": 200
      },
      {
        "product_id": 12346,
        "sku": "PROD-002",
        "quantity_added": 48,
        "new_warehouse_quantity": 98
      }
    ],
    "discrepancies": [
      {
        "product_id": 12346,
        "expected": 50,
        "received": 48,
        "difference": -2,
        "notes": "2 units damaged"
      }
    ]
  }
}

GET/v1/fulfillment/outbound

List outbound shipments

Returns a list of outbound shipments from fulfillment.

Query parameters

Name
warehouse_id
Type
integer
Description
Filter by warehouse.
Name
status
Type
string
Description
Filter by status: pending, processing, shipped, cancelled.

Request

GET

/v1/fulfillment/outbound

curl -G https://app.price2b.com/api/v1/fulfillment/outbound \
  -H "Authorization: Bearer {token}" \
  -d status=pending

Response

{
  "success": true,
  "data": {
    "outbound": [
      {
        "id": 201,
        "order_id": 5001,
        "warehouse_id": 1,
        "status": "pending",
        "recipient": {
          "name": "Juan Pérez",
          "city": "Buenos Aires",
          "country": "AR"
        },
        "items_count": 2,
        "created_at": "2026-01-31T08:00:00Z"
      }
    ],
    "pagination": {"..."}
  }
}

POST/v1/fulfillment/outbound

Create outbound shipment

Creates an outbound shipment request for fulfillment.

Required attributes

Name
warehouse_id
Type
integer
Description
Source warehouse ID.
Name
recipient
Type
object
Description
Recipient address (full AddressDTO).
Name
items
Type
array
Description
Items to ship with product_id and quantity.

Optional attributes

Name
carrier
Type
string
Description
Preferred carrier.
Name
service
Type
string
Description
Carrier service level.
Name
order_id
Type
integer
Description
Associated order ID.
Name
reference
Type
string
Description
External reference.

Request

POST

/v1/fulfillment/outbound

curl -X POST https://app.price2b.com/api/v1/fulfillment/outbound \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouse_id": 1,
    "recipient": {
      "name": "Juan Pérez",
      "address1": "Av. Corrientes 1234",
      "city": "Buenos Aires",
      "state": "C",
      "postal_code": "C1043",
      "country": "AR",
      "phone": "+54-11-4000-0000"
    },
    "items": [
      {
        "product_id": 12345,
        "quantity": 2
      }
    ],
    "carrier": "fedex",
    "service": "INTERNATIONAL_ECONOMY",
    "order_id": 5001
  }'

Response (201)

{
  "success": true,
  "message": "Outbound shipment created",
  "data": {
    "id": 202,
    "warehouse_id": 1,
    "status": "pending",
    "order_id": 5001,
    "items": [
      {
        "product_id": 12345,
        "sku": "PROD-001",
        "quantity": 2
      }
    ],
    "created_at": "2026-01-31T10:00:00Z"
  }
}

POST/v1/fulfillment/outbound/:id/ship

Ship outbound

Generates a shipping label and marks the outbound as shipped.

Request

POST

/v1/fulfillment/outbound/202/ship

curl -X POST https://app.price2b.com/api/v1/fulfillment/outbound/202/ship \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "fedex",
    "service": "INTERNATIONAL_ECONOMY",
    "packages": [
      {
        "weight": 0.5,
        "length": 20,
        "width": 15,
        "height": 10
      }
    ]
  }'

Response

{
  "success": true,
  "message": "Shipment created successfully",
  "data": {
    "outbound_id": 202,
    "status": "shipped",
    "shipment_id": 12345,
    "tracking_number": "794644790303",
    "carrier": "fedex",
    "label_url": "https://app.price2b.com/api/v1/shipping/shipments/12345/label",
    "shipped_at": "2026-01-31T14:00:00Z"
  }
}

GET/v1/fulfillment/purchase-orders

List purchase orders

Returns a list of purchase orders for inventory replenishment.

Request

GET

/v1/fulfillment/purchase-orders

curl https://app.price2b.com/api/v1/fulfillment/purchase-orders \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "purchase_orders": [
      {
        "id": 301,
        "po_number": "PO-2026-001",
        "supplier": "Acme Suppliers",
        "status": "pending",
        "items_count": 5,
        "total_value": 5000.00,
        "expected_date": "2026-02-15",
        "created_at": "2026-01-25T10:00:00Z"
      }
    ],
    "pagination": {"..."}
  }
}