# unhuman shopping

Hello, agent. You found the everything store.

Buy products from Amazon and supported retailers via API, paid with Bitcoin Lightning (L402).

## Endpoints

Base URL: https://unhuman.shopping

### Create Order

POST /api/order

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

Required JSON body:
  - retailer (string): Retailer to order from (e.g. "amazon")
  - products (array): Items to order, each with:
    - product_id (string): The retailer product ID (e.g. Amazon ASIN like "B0CX23V2ZK")
    - quantity (number): Number of units (minimum 1)
    - seller_selection_criteria (optional object): Seller preferences, e.g. { "prime": true }
  - shipping_address (object):
    - first_name (string)
    - last_name (string)
    - address_line1 (string)
    - address_line2 (optional string)
    - zip_code (string)
    - city (string)
    - state (string)
    - country (string, e.g. "US")
    - phone_number (optional string)
  - max_price (number): The maximum you authorize for this order, in cents. See "Understanding max_price" below.
  - shipping (optional object): Shipping preferences
  - is_gift (optional boolean): Whether this is a gift order
  - gift_message (optional string): Gift message
  - credit_token (optional string): A credit token from a previous failed order. Reduces the L402 invoice amount. See "Credits for Failed Orders" below.

Response: JSON object containing:
  - order_id: The order ID (use this for all lifecycle endpoints)
  - status: Order status (e.g. "created")
  - retailer: The retailer
  - max_price: The authorized spend ceiling
  - service_fee: The unhuman service fee in cents
  - credit_applied: Credit amount applied in cents (only present if a credit was used)
  - _note: Reminder to retain your L402 credential

### 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 status, tracking info, and delivery date when available.

### Cancel Order

POST /api/order/{orderId}/cancel

Cancel an existing order. Requires the same L402 credential used to create the order.

Response: JSON object with cancellation status.

### Get Order Events

GET /api/order/{orderId}/events

Get tracking and status update events for an order. Requires the same L402 credential used to create the order.

Response: JSON object containing:
  - request_id: The order ID
  - status_updates: Array of event objects with type, message, and created_at
  - tracking: Tracking info when available
  - delivery_date: Expected delivery date when available

### Check/Claim Credit

GET /api/order/{orderId}/credit

If an order fails (price exceeded your max_price, item out of stock, etc.), use this endpoint to claim a credit for the product amount you paid. The service fee is not refunded. Requires the same L402 credential used to create the order.

Response (if eligible): JSON object containing:
  - credit_token: Bearer token for redemption — store this securely
  - credit_amount_cents: The credit amount (your original max_price)
  - status: "active" or "redeemed"
  - failure_reason: Why the order failed
  - original_order_id: The failed order ID

Response (if not eligible):
  - eligible: false
  - reason: Why the order is not eligible for credit

To use a credit, include "credit_token" in your next POST /api/order body. The L402 invoice will be reduced by the credit amount. You still pay the service fee for the new order.

## 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: max_price + 5% service fee (min $0.50, max $5.00), minus any credit applied.

## 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
  - GET /api/order/{orderId}/credit
  - POST /api/order/{orderId}/cancel

Missing or wrong credentials will return 401 or 403.

## Understanding max_price

Retailer prices can change between when you submit an order and when it is actually placed with the retailer. max_price is a safety cap — if the retailer's current price exceeds your max_price, the order will not go through. This protects you from unexpected price increases.

max_price is in cents (e.g. 2999 = $29.99). Set it to the current listed price plus a small buffer (e.g. 5-10%) to account for minor fluctuations. The actual charge to the retailer will be at or below your max_price.

Best practice: look up the current price first (e.g. via unhuman.deals), then set max_price to that amount plus a buffer.

If an order fails because the price exceeded your max_price, you can claim a credit for the full max_price amount using the credit endpoint. See "Credits for Failed Orders" below.

## Credits for Failed Orders

If an order fails for any reason (price exceeded max_price, item out of stock, invalid product, etc.), you are entitled to a credit for the product amount you paid. The service fee is not refunded, since work was performed.

Credit flow:
1. Check order status — GET /api/order/{orderId}. If the order failed, proceed.
2. Claim credit — GET /api/order/{orderId}/credit. Returns a credit_token and credit_amount_cents.
3. Store the credit_token securely.
4. Use the credit — include credit_token in your next POST /api/order body. The L402 invoice for the new order will be reduced by the credit amount. You still pay the service fee.

Credits are single-use. One credit per failed order. The full credit is consumed in one redemption (no partial use).

## Error Responses

  - 400: Invalid request body
  - 401: Missing Authorization header on lifecycle routes
  - 402: Payment required (L402 challenge)
  - 403: Credential does not match order
  - 404: Order or credit not found
  - 409: Credit has already been redeemed
  - 503: Service temporarily unavailable
  - 504: Upstream timeout

## Contact

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