# unhuman shopping

Hello, agent. You found the everything store.

Buy products from supported retailers via API, paid with Bitcoin Lightning (L402). Search first, then order with a price quote.

> **US only.** Shipping is limited to addresses within the United States.

## Recommended Workflow

1. Search for products → GET /api/catalog?q={query}&retailer={retailer}&zip={zip} (free)
2. Pick a product from the results — note its product_id, retailer, and quote_url
3. Get an exact quote → GET /api/catalog/{productId}?retailer={retailer}&zip={zip} (free)
4. Place the order → POST /api/order with the quote_token and shipping address

## Endpoints

Base URL: https://unhuman.shopping

### Search Products (FREE)

GET /api/catalog?q={query}&retailer={retailer}&zip={zip}&page={page}

Search supported retailers for products. Free — no payment required.
This endpoint is optimized for cheap discovery, not final checkout pricing,
even when q already names a specific product ID.

Query parameters:
  - q (required): Search query or retailer product ID (e.g. "wireless earbuds", "B0CX23V2ZK", "2101922242")
  - retailer (optional): Retailer to search. Supported values: "amazon", "walmart". Default: "amazon"
  - zip (optional): Delivery ZIP code used when building quote_url
  - page (optional): Result page (default 1)

Response: JSON object containing:
  - products: Array of products, each with:
    - asin: Amazon ASIN when retailer is "amazon"
    - product_id: Retailer product ID
    - retailer: Retailer name
    - title: Product name
    - retailer_price_cents: Retailer product price in cents
    - amazon_price_cents: Amazon product price in cents (included for backward compatibility)
    - shipping_estimate_cents: Shipping estimate when already known, otherwise null
    - total_cents: Product + shipping when shipping is already known, otherwise null
    - service_fee_cents: Service fee when total_cents is known, otherwise null
    - estimated_checkout_total_cents: All-in estimate when enough pricing data is available, otherwise null
    - currency: "USD"
    - product_url: Retailer product URL
    - url: Retailer product URL
    - thumbnail: Product image URL
    - rating: Star rating when available
    - is_prime: Whether the item is marked as Prime-eligible (Amazon only; false otherwise)
    - quote_required: Always true for search results
    - quote_url: Call this next to get a single exact quote_token for the chosen product
  - query: The search query
  - page: Current page number
  - retailer: The retailer searched

Example:
  GET /api/catalog?q=wireless+earbuds&retailer=walmart&zip=30312

### Quote One Product (FREE)

GET /api/catalog/{productId}?retailer={retailer}&zip={zip}

Get exact checkout pricing and a quote_token for one chosen product.

Query parameters:
  - retailer (optional): Retailer to quote. Supported values: "amazon", "walmart". Default: "amazon"
  - zip (optional): Delivery ZIP code to associate with the quote

Response: JSON object containing:
  - product:
    - asin: Amazon product ID when retailer is "amazon"
    - product_id: Retailer product ID
    - retailer: Retailer name
    - title: Product name
    - retailer_price_cents: Retailer product price in cents
    - amazon_price_cents: Amazon product price in cents (included for backward compatibility)
    - shipping_estimate_cents: Exact/selected shipping estimate in cents
    - total_cents: Product + shipping
    - service_fee_cents: Service fee in cents
    - checkout_total_cents: Final all-in total used by POST /api/order
    - currency: "USD"
    - product_url: Retailer product URL
    - url: Retailer product URL
    - thumbnail: Product image URL
    - is_prime: Whether the selected offer is Prime-eligible (Amazon only; false otherwise)
    - quote_token: Price quote token (valid 30 minutes) — include this in your order
    - quote_expires_at: When the quote expires (ISO 8601)

Example:
  GET /api/catalog/2101922242?retailer=walmart&zip=30312

### Create Order

POST /api/order

Place an order with a supported retailer. L402-protected — you must pay a Bitcoin Lightning invoice before the order is placed.

Required JSON body:
  - retailer (string): Supported values: "amazon", "walmart"
  - products (array): Exactly one item for now, with:
    - product_id (string): The retailer product ID (e.g. "B0CX23V2ZK" for Amazon, "2101922242" for Walmart)
    - quantity (number): Must be 1
  - shipping_address (object):
    - first_name (string)
    - last_name (string)
    - address_line1 (string)
    - address_line2 (optional string)
    - postal_code (string): Delivery postal/ZIP code (e.g. "30301")
    - city (string)
    - state (string)
    - country (string, e.g. "US")
    - phone_number (string, required): E.164 format (e.g. "+14045551234")
  - quote_token (string): Price quote from /api/catalog/{productId}?retailer={retailer}. Required — quote the chosen product first.
  - shipping (optional object): Shipping preferences
  - is_gift (optional boolean): Whether this is a gift order
  - gift_message (optional string): Gift message

Response: JSON object containing:
  - order_id: The order request_id (use for all lifecycle endpoints)
  - status: Order status
  - retailer: The retailer
  - quoted_total_cents: The price you were quoted (product + shipping)
  - service_fee: The unhuman service fee in cents

### Get Order Status

GET /api/order/{orderId}

Check the status of an existing order. Requires the same L402 credential used to create the order.

Response: JSON object with order details including:
  - request_id: Order ID
  - status: Order status
  - tracking: Tracking information when available
  - delivery_dates: Delivery date estimates when available

### Get Order Events

GET /api/order/{orderId}/events

Get tracking and status updates for an order. Requires the same L402 credential.

Response: JSON object containing order event data. Fields may include:
  - order_id: The order ID
  - events: Array of order event objects

## L402 Payment Flow

1. POST /api/order with your order JSON body
2. Receive 402 Payment Required with headers:
   - WWW-Authenticate: L402 invoice="lnbc...", macaroon="..."
3. Pay the Lightning invoice using any Lightning wallet
4. Retry the same POST with header:
   - Authorization: L402 {macaroon}:{preimage}
5. Order is created and confirmation returned

Pricing: quoted total + 1% service fee (min $0.50, max $5.00).

## Lifecycle Authentication

IMPORTANT: The L402 credential from your successful order creation is your long-term access credential for that order.

After creating an order, persist your Authorization header value and replay it for all lifecycle calls:
  - GET /api/order/{orderId}
  - GET /api/order/{orderId}/events

Missing or wrong credentials will return 401 or 403.

## Error Responses

  - 400: Invalid request body or expired/invalid quote
  - 401: Missing Authorization header on lifecycle routes
  - 402: Payment required (L402 challenge)
  - 403: Credential does not match order
  - 404: Order not found
  - 503: Service temporarily unavailable
  - 504: Upstream timeout

## Contact

- Email: support@unhuman.store
- Website: https://unhuman.shopping