Orders Reference

Orders are created exclusively via payment provider webhooks. You cannot create orders directly via API. This reference documents the Order entity structure and read-only operations.

Order Status Flow

Status Meanings:

paid - Payment received, awaiting fulfillment
fulfilled - Order shipped and completed
cancelled - Order cancelled before fulfillment
refunded - Payment refunded to customer

Note: Unlike traditional e-commerce systems, there is no pending status. Orders go directly to paid when payment succeeds.

Order Entity Fields

Identification Fields

Field	Type	Description
`id`	uuid	Unique order ID
`orderNumber`	string	Human-readable order number (e.g., "ORD-000042")
`storeId`	uuid	Parent store
`customerId`	uuid	Customer who placed order

Financial Fields

Field	Type	Description
`subtotal`	decimal	Total before tax/shipping
`tax`	decimal	Tax amount
`taxRate`	decimal	Applied tax rate (e.g., 0.08 for 8%)
`shipping`	decimal	Shipping cost
`discount`	decimal	Total discount applied
`discountCode`	string	Promo code used (if any)
`total`	decimal	Final total
`currency`	string	ISO 4217 currency code (e.g., "USD")

Status Fields

Field	Type	Values	Description
`status`	enum	pending, paid, fulfilled, cancelled	Order status
`paymentStatus`	enum	pending, processing, succeeded, failed, refunded, partially_refunded, cancelled	Payment status

Payment Provider Fields

Field	Type	Description
`paymentProvider`	string	"stripe", "paypal", or "square"
`paymentId`	string	Provider's transaction ID (e.g., Stripe PaymentIntent ID)
`paymentMethod`	string	Card type, PayPal wallet, etc.
`paymentDetails`	json	Provider-specific metadata (see below)

paymentDetails examples:

// Stripe
{
  "last4": "4242",
  "brand": "visa",
  "expMonth": 12,
  "expYear": 2025
}
 
// PayPal
{
  "email": "buyer@example.com",
  "payerStatus": "verified"
}
 
// Square
{
  "last4": "1111",
  "cardBrand": "VISA"
}

Address Snapshots (JSON)

Addresses are stored as JSON snapshots because customer addresses may change later.

Field	Type	Description
`shippingAddress`	json	Address where order ships to
`billingAddress`	json	Address on payment method

Address structure:

{
  "firstName": "John",
  "lastName": "Doe",
  "address1": "123 Main St",
  "address2": null,
  "city": "San Francisco",
  "region": "CA",
  "postalCode": "94103",
  "country": "US",
  "company": null,
  "phone": "+1-555-0123"
}

Timeline Fields

Field	Type	Description
`placedAt`	datetime	When order was finalized
`paidAt`	datetime	When payment succeeded
`fulfilledAt`	datetime	When shipped/completed
`cancelledAt`	datetime	When cancelled
`createdAt`	datetime	When order was created (immutable)
`updatedAt`	datetime	Last update time

Notes

Field	Type	Description
`customerNote`	string	Note customer entered at checkout
`merchantNote`	string	Internal merchant notes (editable)

Order Items

Field	Type	Description
`items`	array	Array of OrderItem objects (see below)

Order Item Fields

Each order contains line items:

{
  "id": "item_123",
  "orderId": "order_456",
  "productId": "prod_789",
  "titleSnapshot": "Blue Shirt",
  "skuSnapshot": "BLUE-SHIRT-001",
  "quantity": 2,
  "unitPrice": "39.99",
  "variantTitle": "Blue / Medium",
  "attributesSnapshot": {
    "color": "blue",
    "size": "m"
  },
  "lineDiscount": "0.00",
  "primaryImageId": "media_abc"
}

Field	Type	Description
`id`	uuid	Item ID
`orderId`	uuid	Parent order
`productId`	uuid	Link to product
`titleSnapshot`	string	Product title at purchase time
`skuSnapshot`	string	SKU at purchase time
`quantity`	integer	Quantity ordered
`unitPrice`	decimal	Price per unit (at purchase)
`variantTitle`	string	Variant description (e.g., "Blue / Medium")
`attributesSnapshot`	json	Product attributes (color, size, etc.)
`lineDiscount`	decimal	Per-line discount
`primaryImageId`	string	Product image ID at purchase

Example Response

{
  "item": {
    "id": "order_abc123def456",
    "orderNumber": "ORD-000042",
    "customerId": "cust_xyz789",
    "storeId": "store_123",
    "subtotal": "79.98",
    "tax": "6.40",
    "taxRate": "0.08",
    "shipping": "10.00",
    "discount": "6.39",
    "discountCode": "SAVE10",
    "total": "89.99",
    "currency": "USD",
    "status": "paid",
    "paymentStatus": "succeeded",
    "paymentProvider": "stripe",
    "paymentId": "pi_1ABC123XYZ",
    "paymentMethod": "card",
    "paymentDetails": {
      "last4": "4242",
      "brand": "visa",
      "expMonth": 12,
      "expYear": 2025
    },
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "123 Main St",
      "address2": null,
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94103",
      "country": "US",
      "company": null,
      "phone": "+1-555-0123"
    },
    "billingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "123 Main St",
      "address2": null,
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94103",
      "country": "US"
    },
    "customerNote": "Please leave at door",
    "merchantNote": "VIP customer - priority shipping",
    "placedAt": "2024-01-15T10:30:00Z",
    "paidAt": "2024-01-15T10:30:05Z",
    "fulfilledAt": null,
    "cancelledAt": null,
    "items": [
      {
        "id": "item_1",
        "productId": "prod_abc",
        "titleSnapshot": "Blue Shirt",
        "skuSnapshot": "BLUE-SHIRT-001",
        "quantity": 2,
        "unitPrice": "39.99",
        "variantTitle": "Blue / Medium",
        "attributesSnapshot": {
          "color": "blue",
          "size": "m"
        },
        "lineDiscount": "0.00",
        "primaryImageId": "media_xyz"
      },
      {
        "id": "item_2",
        "productId": "prod_def",
        "titleSnapshot": "T-Shirt",
        "skuSnapshot": "TSHIRT-001",
        "quantity": 1,
        "unitPrice": "24.99",
        "variantTitle": null,
        "attributesSnapshot": {},
        "lineDiscount": "6.39",
        "primaryImageId": "media_123"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:05Z"
  }
}

API Operations

List Orders

Endpoint: GET /api/stores/{storeId}/orders

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: pending, paid, fulfilled, cancelled
`paymentStatus`	string	Filter by payment status
`customerId`	string	Filter by customer ID
`orderNumber`	string	Filter by order number
`limit`	integer	Page size (1-200, default 50)
`offset`	integer	Skip count (default 0)

Examples:

# List all paid orders
curl https://api.barecommercecore.com/api/stores/{storeId}/orders?status=paid \
  -H "X-API-Key: sk_live_your_key"
 
# List orders by customer
curl https://api.barecommercecore.com/api/stores/{storeId}/orders?customerId={customerId} \
  -H "X-API-Key: sk_live_your_key"
 
# Search by order number
curl https://api.barecommercecore.com/api/stores/{storeId}/orders?orderNumber=ORD-000042 \
  -H "X-API-Key: sk_live_your_key"
 
# Paginated request
curl "https://api.barecommercecore.com/api/stores/{storeId}/orders?limit=20&offset=40" \
  -H "X-API-Key: sk_live_your_key"

Response: 200 OK

{
  "items": [...array of orders...],
  "total": 150
}

Get Single Order

Endpoint: GET /api/stores/{storeId}/orders/{orderId}

curl https://api.barecommercecore.com/api/stores/{storeId}/orders/{orderId} \
  -H "X-API-Key: sk_live_your_key"

Response: 200 OK - Full order object (see example above)

Record a Refund

Endpoint: POST /api/stores/{storeId}/orders/{orderId}/refund

This endpoint records a refund for merchant tracking. For actual refund processing, use your payment provider's API.

Request:

{
  "amount": "39.99",
  "reason": "Customer requested",
  "refundId": "re_1ABC123"
}

Fields:

amount (required) - Refund amount
reason (optional) - Reason for refund
refundId (optional) - Provider's refund ID (from Stripe, PayPal, etc.)

Example:

curl -X POST https://api.barecommercecore.com/api/stores/{storeId}/orders/{orderId}/refund \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "39.99",
    "reason": "Customer request",
    "refundId": "re_1ABC123"
  }'

Response: 200 OK

{
  "item": {
    "refundId": "ref_123",
    "amount": "39.99",
    "recordedAt": "2024-01-15T10:35:00Z"
  }
}

Common Tasks

Get Total Revenue for Period

// List all paid orders (adjust filters as needed)
const response = await fetch(
  'https://api.barecommercecore.com/api/stores/{storeId}/orders?status=paid&limit=200',
  { headers: { 'X-API-Key': apiKey } }
);
 
const { items } = await response.json();
 
// Sum totals
const revenue = items.reduce((sum, order) => 
  sum + parseFloat(order.total), 0
);
 
console.log(`Total revenue: $${revenue.toFixed(2)}`);

Get Orders by Date Range

// List recent orders
const orders = await fetchOrders({ status: 'paid', limit: 100 });
 
// Filter by date (BareCommerce doesn't support date filters in API)
const startDate = new Date('2024-01-01');
const endDate = new Date('2024-01-31');
 
const january = orders.filter(order => {
  const date = new Date(order.placedAt);
  return date >= startDate && date <= endDate;
});
 
console.log(`Orders in January: ${january.length}`);

Get Customer Order History

const customerId = 'cust_123';
 
const response = await fetch(
  `https://api.barecommercecore.com/api/stores/{storeId}/orders?customerId=${customerId}`,
  { headers: { 'X-API-Key': apiKey } }
);
 
const { items: customerOrders } = await response.json();
 
console.log(`Customer has ${customerOrders.length} orders`);
console.log(`Total spent: $${
  customerOrders.reduce((sum, o) => sum + parseFloat(o.total), 0).toFixed(2)
}`);

Process Fulfilled Orders

const fulfilled = await fetch(
  'https://api.barecommercecore.com/api/stores/{storeId}/orders?status=fulfilled',
  { headers: { 'X-API-Key': apiKey } }
);
 
const { items } = await fulfilled.json();
 
for (const order of items) {
  // Send shipment tracking to customer
  await sendTrackingEmail(order.customerId, order.orderNumber);
}

Important Notes

Orders are read-only - You cannot create or update orders via API (except merchantNote)
Orders are immutable - Once created, order data doesn't change (except status and merchantNote)
Payment is authoritative - Trust paymentStatus and paymentProvider as the source of truth
Addresses are snapshots - Stored as JSON because customer data may change
Items are snapshots - Product prices/details at purchase time, not current
No pending status - Orders go straight to paid when payment succeeds

Next Steps

See Payment Guides to understand how orders are created
See Webhooks Guide to receive order events
Back to API Reference

Products Customers