Internal API Documentation

Docs for the Cart2Table Inventory & Fulfillment API

Base Information

  • Base URL: https://cart2table.dev/api/
  • Authentication: None required for this challenge
  • Data Format: JSON
  • Error Handling: Errors are returned as JSON objects with relevant HTTP status codes

Models

Cart

Field Type Description
id string Cart ID in format CART_ followed by 8 hex characters
created_at datetime When the cart was created
updated_at datetime When the cart was last updated
cart_items array List of cart items in this cart
order object Associated order, null if not yet ordered

Cart Item

Field Type Description
id string UUID of the cart item
cart_id string Cart ID in format CART_ followed by 8 hex characters
product_id string UUID of the product in this item
quantity_ordered integer Number of units ordered (minimum: 1)
product object The associated product details

Product

Field Type Description
id string UUID of the product (required)
name string Name of the product (required)
base_price integer Base price in cents (required, minimum: 0)

Order

Field Type Description
id string Internal UUID for the order (required)
cart_id string Cart ID in format CART_ followed by 8 hex characters (required)
paypal_order_id string Order ID from PayPal API (required)
total_due integer Total amount due in cents (required, minimum: 1)
status string Order payment status based on payments received. One of: created, partially_paid, fully_paid
fulfilled_at datetime When the order was fulfilled, null if not fulfilled
total_paid integer Total amount paid in cents (sum of payment amounts)
remaining_balance integer Remaining balance to be paid in cents
payments array List of payments made for this order

Payment

Field Type Description
id string Internal UUID for the payment (required)
order_id string UUID of the order this payment belongs to
capture_id string Unique capture ID from PayPal API. Must be unique across all payments. (required)
amount_captured integer Amount captured in cents. Must be positive. (required)
date_received datetime When the payment was received (required)

Endpoints

GET /api/cart/:id

Retrieves a cart and its associated items. Create a cart using POST /api/cart before calling this endpoint.

Response (200 OK)

{
  "id": "CART_1A2B3C4D",
  "created_at": "2025-01-23T12:00:00-05:00",
  "updated_at": "2025-01-23T12:00:00-05:00",
  "cart_items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "cart_id": "CART_1A2B3C4D",
      "product_id": "123e4567-e89b-12d3-a456-426614174001",
      "quantity_ordered": 2,
      "product": {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "name": "Farm Fresh Tomatoes",
        "base_price": 2999
      }
    }
  ],
  "order": null
}

Error Responses

404 Not Found

{
  "message": "Cart not found"
}
POST /api/cart

Creates a new cart with a random selection of 2-5 products and random quantities. This is to aid in testing.

Response (201 Created)

{
  "message": "Random cart created successfully",
  "cart_id": "CART_12345678"
}
POST /api/order

Creates a new order for a cart. If the cart already has an order, the existing order will be replaced with the new one.

Request Body

{
  "cart_id": "CART_12345678",
  "paypal_order_id": "PAYPAL-123"
}

Response (201 Created)

{
  "message": "Order created successfully"
}

Error Responses

404 Not Found

{
  "message": "Cart not found"
}

422 Unprocessable Entity

{
  "message": [
    "Paypal order can't be blank"
  ]
}
POST /api/payment

Records a payment for an order with PayPal capture details. Multiple payments can be recorded for a single order. Once payment is captured, this may trigger order fulfillment if the order becomes fully paid.

Request Body

{
  "paypal_order_id": "PAYPAL-123",
  "capture_id": "CAP-123",
  "amount_captured": 1099
}

Response (201 Created)

{
  "message": "Payment created successfully",
  "order_status": "created"
}

Error Responses

404 Not Found

{
  "message": "Order not found"
}

422 Unprocessable Entity

{
  "message": [
    "Amount captured must be greater than 0",
    "Capture has already been taken"
  ]
}