### Clone and Run Merchant API Project

Source: https://merchant.ygwyg.org/docs/llms

Instructions to clone the Merchant project from GitHub, install dependencies, initialize the store and API keys, and start the development server.

```bash
git clone https://github.com/ygwyg/merchant
cd merchant && npm install
npx tsx scripts/init.ts  # Creates store + API keys
npm run dev               # http://localhost:8787
```

--------------------------------

### Start Merchant Development Server

Source: https://merchant.ygwyg.org/docs/index

Starts the development server for the Merchant API, typically used for local testing and development.

```bash
npm run dev
```

--------------------------------

### Clone and Install Merchant API

Source: https://merchant.ygwyg.org/docs/index

This snippet demonstrates how to clone the Merchant API repository from GitHub and install its dependencies using npm.

```bash
git clone https://github.com/ygwyg/merchant
cd merchant && npm install
```

--------------------------------

### Complete Checkout Flow: Create Cart

Source: https://merchant.ygwyg.org/docs/llms

Example cURL command to create a shopping cart for a customer.

```bash
# 1. Create cart
curl -X POST http://localhost:8787/v1/carts \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"customer_email":"buyer@example.com"}'
```

--------------------------------

### Initialize Merchant Store

Source: https://merchant.ygwyg.org/docs/index

Initializes your store using a TypeScript script. This is a crucial step after cloning and installing the project.

```bash
npx tsx scripts/init.ts
```

--------------------------------

### Get Inventory by SKU API Response

Source: https://merchant.ygwyg.org/docs/llms

Example JSON response for retrieving inventory by SKU, showing on-hand, reserved, and available quantities.

```json
{
  "sku": "TEE-BLK-M",
  "on_hand": 100,
  "reserved": 5,
  "available": 95
}
```

--------------------------------

### Stripe Setup API

Source: https://merchant.ygwyg.org/docs/index

Endpoint for connecting your Stripe account to the Merchant backend.

```APIDOC
## POST /v1/setup/stripe

### Description
Connects your Stripe account by providing your Stripe secret key. This is typically done during the initial setup of your merchant store.

### Method
POST

### Endpoint
/v1/setup/stripe

### Parameters
#### Path Parameters

#### Query Parameters

#### Request Body
- **stripe_secret_key** (string) - Required - Your Stripe secret key (starts with `sk_test_` or `sk_live_`).

### Request Example
```bash
curl -X POST http://localhost:8787/v1/setup/stripe \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"stripe_secret_key":"sk_test_..."}'
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the Stripe account was successfully connected.

#### Response Example
```json
{
  "message": "Stripe account connected successfully."
}
```
```

--------------------------------

### Create Product API Response (201)

Source: https://merchant.ygwyg.org/docs/llms

Example JSON response for creating a product, including its ID, status, and variants.

```json
{
  "id": "uuid",
  "title": "T-Shirt",
  "description": "Premium cotton tee",
  "status": "active",
  "variants": []
}
```

--------------------------------

### Get Product API Endpoint

Source: https://merchant.ygwyg.org/docs/llms

GET request to retrieve details for a specific product by its ID. Requires an admin API key.

```http
GET /v1/products/{id}
Authorization: Bearer sk_...
```

--------------------------------

### Product API - Create Product

Source: https://merchant.ygwyg.org/docs/index

Example JSON payload for creating a new product in the Merchant API. It requires a `title` and optionally accepts a `description`.

```json
{
  "title": "Classic Tee",
  "description": "Premium cotton t-shirt"
}
```

--------------------------------

### Create Product Variant API Response (201)

Source: https://merchant.ygwyg.org/docs/llms

Example JSON response after successfully creating a product variant, including its details.

```json
{
  "id": "uuid",
  "sku": "TEE-BLK-M",
  "title": "Black / M",
  "price_cents": 2999,
  "image_url": null
}
```

--------------------------------

### Get Inventory by SKU API Endpoint

Source: https://merchant.ygwyg.org/docs/llms

GET request to retrieve inventory details for a specific SKU.

```http
GET /v1/inventory?sku=TEE-BLK-M
Authorization: Bearer sk_...
```

--------------------------------

### Complete Checkout Flow: Add Items to Cart

Source: https://merchant.ygwyg.org/docs/llms

Example cURL command to add items to an existing shopping cart.

```bash
# 2. Add items
curl -X POST http://localhost:8787/v1/carts/{cart_id}/items \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"items":[{"sku":"TEE-BLK-M","qty":1}]}'
```

--------------------------------

### List Products API Endpoint

Source: https://merchant.ygwyg.org/docs/llms

GET request to list all products in the store. Requires an admin API key for authorization.

```http
GET /v1/products
Authorization: Bearer sk_...
```

--------------------------------

### Complete Checkout Flow: Checkout

Source: https://merchant.ygwyg.org/docs/llms

Example cURL command to initiate the checkout process for a shopping cart, providing success and cancel URLs.

```bash
# 3. Checkout
curl -X POST http://localhost:8787/v1/carts/{cart_id}/checkout \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"success_url":"https://site.com/thanks","cancel_url":"https://site.com/cart"}'
```

--------------------------------

### List Products API Response

Source: https://merchant.ygwyg.org/docs/llms

Example JSON response for the List Products endpoint, detailing product information including variants.

```json
{
  "items": [
    {
      "id": "uuid",
      "title": "T-Shirt",
      "description": "Premium cotton tee",
      "status": "active",
      "created_at": "2025-01-01T00:00:00Z",
      "variants": [
        {
          "id": "uuid",
          "sku": "TEE-BLK-M",
          "title": "Black / M",
          "price_cents": 2999,
          "image_url": null
        }
      ]
    }
  ]
}
```

--------------------------------

### Create Cart API Response

Source: https://merchant.ygwyg.org/docs/llms

Example JSON response for creating a cart, including its ID, status, currency, customer email, and expiration time.

```json
{
  "id": "uuid",
  "status": "open",
  "currency": "USD",
  "customer_email": "buyer@example.com",
  "items": [],
  "expires_at": "2025-01-01T12:30:00Z"
}
```

--------------------------------

### List Inventory API Response

Source: https://merchant.ygwyg.org/docs/llms

Example JSON response for the List Inventory endpoint, detailing stock levels for each SKU.

```json
{
  "items": [
    {
      "sku": "TEE-BLK-M",
      "on_hand": 100,
      "reserved": 5,
      "available": 95,
      "variant_title": "Black / M",
      "product_title": "T-Shirt"
    }
  ]
}
```

--------------------------------

### Get Image

Source: https://merchant.ygwyg.org/docs/llms

Retrieves an image using its key. No authentication is required for this endpoint, and the response includes cache headers.

```APIDOC
## GET /v1/images/{key}

### Description
Retrieves an image by its key. No authentication required. Returns image with cache headers.

### Method
GET

### Endpoint
/v1/images/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique key identifying the image.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET https://your-domain.com/v1/images/store_id/uuid.jpg
```

### Response
#### Success Response (200)
(Returns the image data directly with appropriate Content-Type and caching headers.)

#### Response Example
(The response body will be the image data itself.)
```

--------------------------------

### Get Image API Request

Source: https://merchant.ygwyg.org/docs/llms

Retrieves an image by its key. No authentication is required, and the response includes cache headers.

```http
GET /v1/images/{key}
```

--------------------------------

### Get Order

Source: https://merchant.ygwyg.org/docs/llms

Retrieves details for a specific order using its unique ID.

```APIDOC
## GET /v1/orders/{id}

### Description
Retrieves details for a specific order.

### Method
GET

### Endpoint
/v1/orders/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the order.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET https://your-domain.com/v1/orders/uuid \
  -H "Authorization: Bearer sk_..."
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the order.
- **number** (string) - Order number.
- **status** (string) - Current status of the order.
- **customer_email** (string) - Email of the customer.
- **ship_to** (object) - Shipping address details.
  - **line1** (string) - Street address.
  - **city** (string) - City.
  - **state** (string) - State or province.
  - **postal_code** (string) - Postal code.
  - **country** (string) - Country code.
- **amounts** (object) - Contains pricing details.
  - **subtotal_cents** (integer) - Subtotal amount in cents.
  - **tax_cents** (integer) - Tax amount in cents.
  - **shipping_cents** (integer) - Shipping cost in cents.
  - **total_cents** (integer) - Total amount in cents.
  - **currency** (string) - Currency code.
- **stripe** (object) - Stripe-specific payment details.
  - **checkout_session_id** (string) - Stripe checkout session ID.
  - **payment_intent_id** (string) - Stripe payment intent ID.
- **items** (array) - Array of items included in the order.
  - **sku** (string) - Stock Keeping Unit.
  - **title** (string) - Product title.
  - **qty** (integer) - Quantity ordered.
  - **unit_price_cents** (integer) - Unit price in cents.
- **created_at** (string) - Timestamp when the order was created.

#### Response Example
```json
{
  "id": "uuid",
  "number": "ORD-00001",
  "status": "paid",
  "customer_email": "buyer@example.com",
  "ship_to": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "amounts": {
    "subtotal_cents": 5998,
    "tax_cents": 0,
    "shipping_cents": 0,
    "total_cents": 5998,
    "currency": "USD"
  },
  "stripe": {
    "checkout_session_id": "cs_...",
    "payment_intent_id": "pi_..."
  },
  "items": [
    {
      "sku": "TEE-BLK-M",
      "title": "Black / M",
      "qty": 2,
      "unit_price_cents": 2999
    }
  ],
  "created_at": "2025-01-01T12:00:00Z"
}
```
```

--------------------------------

### List Inventory API Endpoint

Source: https://merchant.ygwyg.org/docs/llms

GET request to list all inventory items, showing on-hand, reserved, and available quantities, along with product and variant titles.

```http
GET /v1/inventory
Authorization: Bearer sk_...
```

--------------------------------

### Checkout Cart API Response

Source: https://merchant.ygwyg.org/docs/llms

Example JSON response for initiating checkout, providing a Stripe checkout URL and session ID for payment redirection.

```json
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
  "stripe_checkout_session_id": "cs_..."
}
```

--------------------------------

### Get Order API Request

Source: https://merchant.ygwyg.org/docs/llms

Retrieves a specific order by its ID. Requires Bearer token authentication.

```http
GET /v1/orders/{id}
Authorization: Bearer sk_...
```

--------------------------------

### Add Items to Cart API Response

Source: https://merchant.ygwyg.org/docs/llms

Example JSON response after adding items to a cart, showing updated cart contents with SKUs, quantities, and prices.

```json
{
  "id": "uuid",
  "status": "open",
  "currency": "USD",
  "customer_email": "buyer@example.com",
  "items": [
    {
      "sku": "TEE-BLK-M",
      "title": "Black / M",
      "qty": 2,
      "unit_price_cents": 2999
    },
    {
      "sku": "CAP-BLK",
      "title": "Black",
      "qty": 1,
      "unit_price_cents": 2499
    }
  ],
  "expires_at": "2025-01-01T12:30:00Z"
}
```

--------------------------------

### Create Product API Endpoint

Source: https://merchant.ygwyg.org/docs/llms

POST request to create a new product. Requires title and description. Returns the created product details.

```http
POST /v1/products
Authorization: Bearer sk_...
Content-Type: application/json

{
  "title": "T-Shirt",
  "description": "Premium cotton tee"
}
```

--------------------------------

### Stripe Webhook Listener for Local Development

Source: https://merchant.ygwyg.org/docs/index

Command to set up Stripe CLI to listen for webhooks and forward them to your local development server. This is essential for testing webhook functionality.

```bash
stripe listen --forward-to localhost:8787/v1/webhooks/stripe
```

--------------------------------

### Configure Stripe Webhook

Source: https://merchant.ygwyg.org/docs/llms

Sets up the Stripe webhook endpoint in the Stripe Dashboard. The provided endpoint is `https://your-domain.com/v1/webhooks/stripe`. Handles `checkout.session.completed` events.

```bash
POST /v1/webhooks/stripe

Configure in Stripe Dashboard. Set endpoint to:
`https://your-domain.com/v1/webhooks/stripe`
```

--------------------------------

### Webhook Configuration

Source: https://merchant.ygwyg.org/docs/index

Information on configuring Stripe webhooks.

```APIDOC
## POST /v1/webhooks/stripe

### Description
Handles incoming Stripe webhooks, specifically `checkout.session.completed`. This endpoint is responsible for creating orders and deducting inventory upon successful checkout.

### Method
POST

### Endpoint
/v1/webhooks/stripe

### Parameters
#### Path Parameters

#### Query Parameters

#### Request Body
Stripe sends a JSON payload with event details. The structure depends on the specific Stripe event.

### Request Example
(Stripe sends this payload automatically)
```json
{
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_...",
      "payment_status": "paid",
      "metadata": {
        "cart_id": "cart_abc123"
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the webhook was received and processed.

#### Response Example
```json
{
  "message": "Stripe webhook received and processed."
}
```

### Local Development Setup
To test webhooks locally, use the Stripe CLI:
```bash
stripe listen --forward-to localhost:8787/v1/webhooks/stripe
```
```

--------------------------------

### Products API

Source: https://merchant.ygwyg.org/docs/llms

Endpoints for managing product listings, including retrieving, creating, and updating products and their variants.

```APIDOC
## GET /v1/products

### Description
Lists all available products.

### Method
GET

### Endpoint
/v1/products

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter products by status (e.g., 'active', 'draft').

### Request Example
```bash
curl -X GET \
  http://localhost:8787/v1/products \
  -H "Authorization: Bearer sk_..."
```

### Response
#### Success Response (200)
- **items** (array) - An array of product objects.
  - **id** (string) - Unique identifier for the product.
  - **title** (string) - The name of the product.
  - **description** (string) - A detailed description of the product.
  - **status** (string) - The current status of the product (e.g., 'active', 'draft').
  - **created_at** (string) - Timestamp of when the product was created.
  - **variants** (array) - An array of product variant objects.
    - **id** (string) - Unique identifier for the variant.
    - **sku** (string) - Stock Keeping Unit for the variant.
    - **title** (string) - The name of the variant (e.g., 'Black / M').
    - **price_cents** (integer) - The price of the variant in cents.
    - **image_url** (string) - URL of the variant's image (nullable).

#### Response Example
```json
{
  "items": [
    {
      "id": "uuid",
      "title": "T-Shirt",
      "description": "Premium cotton tee",
      "status": "active",
      "created_at": "2025-01-01T00:00:00Z",
      "variants": [
        {
          "id": "uuid",
          "sku": "TEE-BLK-M",
          "title": "Black / M",
          "price_cents": 2999,
          "image_url": null
        }
      ]
    }
  ]
}
```

## GET /v1/products/{id}

### Description
Retrieves a specific product by its ID.

### Method
GET

### Endpoint
/v1/products/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the product.

### Request Example
```bash
curl -X GET \
  http://localhost:8787/v1/products/uuid \
  -H "Authorization: Bearer sk_..."
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the product.
- **title** (string) - The name of the product.
- **description** (string) - A detailed description of the product.
- **status** (string) - The current status of the product.
- **variants** (array) - An array of product variant objects.

#### Response Example
```json
{
  "id": "uuid",
  "title": "T-Shirt",
  "description": "Premium cotton tee",
  "status": "active",
  "variants": [
    {
      "id": "uuid",
      "sku": "TEE-BLK-M",
      "title": "Black / M",
      "price_cents": 2999,
      "image_url": null
    }
  ]
}
```

## POST /v1/products

### Description
Creates a new product.

### Method
POST

### Endpoint
/v1/products

### Parameters
#### Request Body
- **title** (string) - Required - The name of the product.
- **description** (string) - Optional - A detailed description of the product.

### Request Example
```json
{
  "title": "T-Shirt",
  "description": "Premium cotton tee"
}
```

### Response
#### Success Response (201)
- **id** (string) - Unique identifier for the newly created product.
- **title** (string) - The name of the product.
- **description** (string) - A detailed description of the product.
- **status** (string) - The current status of the product (defaults to 'active').
- **variants** (array) - An empty array initially.

#### Response Example
```json
{
  "id": "uuid",
  "title": "T-Shirt",
  "description": "Premium cotton tee",
  "status": "active",
  "variants": []
}
```

## PATCH /v1/products/{id}

### Description
Updates an existing product.

### Method
PATCH

### Endpoint
/v1/products/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the product to update.

#### Request Body
- **title** (string) - Optional - The new name of the product.
- **description** (string) - Optional - The new description of the product.
- **status** (string) - Optional - The new status of the product ('active' or 'draft').

### Request Example
```json
{
  "title": "Updated Title",
  "description": "New description",
  "status": "draft"
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the updated product.
- **title** (string) - The updated name of the product.
- **description** (string) - The updated description of the product.
- **status** (string) - The updated status of the product.
- **variants** (array) - The product's variants.

#### Response Example
```json
{
  "id": "uuid",
  "title": "Updated Title",
  "description": "New description",
  "status": "draft",
  "variants": []
}
```

## POST /v1/products/{id}/variants

### Description
Adds a new variant to an existing product.

### Method
POST

### Endpoint
/v1/products/{id}/variants

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the product to add a variant to.

#### Request Body
- **sku** (string) - Required - The Stock Keeping Unit for the variant.
- **title** (string) - Required - The name of the variant (e.g., 'Black / M').
- **price_cents** (integer) - Required - The price of the variant in cents.
- **image_url** (string) - Optional - URL of the variant's image.

### Request Example
```json
{
  "sku": "TEE-BLK-M",
  "title": "Black / M",
  "price_cents": 2999,
  "image_url": "https://..."
}
```

### Response
#### Success Response (201)
- **id** (string) - Unique identifier for the newly created variant.
- **sku** (string) - The Stock Keeping Unit for the variant.
- **title** (string) - The name of the variant.
- **price_cents** (integer) - The price of the variant in cents.
- **image_url** (string) - URL of the variant's image.

#### Response Example
```json
{
  "id": "uuid",
  "sku": "TEE-BLK-M",
  "title": "Black / M",
  "price_cents": 2999,
  "image_url": null
}
```
```

--------------------------------

### Create Product Variant API Endpoint

Source: https://merchant.ygwyg.org/docs/llms

POST request to add a new variant to a product. Requires SKU, title, and price in cents. Can include an image URL.

```http
POST /v1/products/{id}/variants
Authorization: Bearer sk_...
Content-Type: application/json

{
  "sku": "TEE-BLK-M",
  "title": "Black / M",
  "price_cents": 2999,
  "image_url": "https://..."
}
```

--------------------------------

### Product Variant API - Create Variant

Source: https://merchant.ygwyg.org/docs/index

JSON payload for creating a product variant. Requires `sku`, `title`, and `price_cents`. An optional `image_url` can also be provided.

```json
{
  "sku": "TEE-BLK-M",
  "title": "Black / Medium",
  "price_cents": 2999
}
```

--------------------------------

### Connect Stripe Account via API

Source: https://merchant.ygwyg.org/docs/index

This `curl` command shows how to connect your Stripe account to the Merchant API by sending a POST request with your Stripe secret key.

```bash
curl -X POST http://localhost:8787/v1/setup/stripe \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"stripe_secret_key":"sk_test-..."}'
```

--------------------------------

### Variant Management API

Source: https://merchant.ygwyg.org/docs/index

Endpoints for managing product variants, including creating them.

```APIDOC
## POST /v1/products/:id/variants

### Description
Creates a variant for a product. Automatically creates an inventory record.

### Method
POST

### Endpoint
/v1/products/:id/variants

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the product to add the variant to.

#### Query Parameters

#### Request Body
- **sku** (string) - Required - Unique identifier for the variant.
- **title** (string) - Required - e.g., "Black / Medium".
- **price_cents** (integer) - Required - Price in cents (e.g., 2999 for $29.99).
- **image_url** (string) - Optional - URL for the variant's image.

### Request Example
```json
{
  "sku": "TEE-BLK-M",
  "title": "Black / Medium",
  "price_cents": 2999
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the newly created variant.
- **productId** (string) - The ID of the product this variant belongs to.
- **sku** (string) - The SKU of the variant.
- **title** (string) - The title of the variant.
- **price_cents** (integer) - The price of the variant in cents.
- **imageUrl** (string) - The image URL of the variant.

#### Response Example
```json
{
  "id": "var_xyz789",
  "productId": "prod_abc123",
  "sku": "TEE-BLK-M",
  "title": "Black / Medium",
  "price_cents": 2999,
  "imageUrl": null
}
```
```

--------------------------------

### Product Management API

Source: https://merchant.ygwyg.org/docs/index

Endpoints for managing products, including creating, retrieving, and updating them.

```APIDOC
## GET /v1/products

### Description
Returns all products with their variants.

### Method
GET

### Endpoint
/v1/products

### Parameters

#### Query Parameters

#### Request Body

### Request Example

### Response
#### Success Response (200)
- **items** (array) - List of products.
  - **id** (string) - Product ID.
  - **title** (string) - Product title.
  - **status** (string) - Product status (`active` or `draft`).
  - **variants** (array) - List of product variants.

#### Response Example
```json
{
  "items": [
    {
      "id": "prod_abc123",
      "title": "Classic Tee",
      "status": "active",
      "variants": [...] 
    }
  ]
}
```

## POST /v1/products

### Description
Creates a new product.

### Method
POST

### Endpoint
/v1/products

### Parameters

#### Path Parameters

#### Query Parameters

#### Request Body
- **title** (string) - Required - Product name.
- **description** (string) - Optional - Product description.

### Request Example
```json
{
  "title": "Classic Tee",
  "description": "Premium cotton t-shirt"
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the newly created product.
- **title** (string) - The title of the product.
- **description** (string) - The description of the product.
- **status** (string) - The status of the product.

#### Response Example
```json
{
  "id": "prod_new123",
  "title": "Classic Tee",
  "description": "Premium cotton t-shirt",
  "status": "active"
}
```

## PATCH /v1/products/:id

### Description
Updates a product. All fields are optional.

### Method
PATCH

### Endpoint
/v1/products/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the product to update.

#### Query Parameters

#### Request Body
- **title** (string) - Optional - Product name.
- **status** (string) - Optional - Product status (`active` or `draft`).

### Request Example
```json
{
  "status": "draft"
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the updated product.
- **title** (string) - The updated title of the product.
- **status** (string) - The updated status of the product.

#### Response Example
```json
{
  "id": "prod_abc123",
  "title": "Classic Tee",
  "status": "draft"
}
```
```

--------------------------------

### Cart API - Create Cart

Source: https://merchant.ygwyg.org/docs/index

JSON payload for creating a new shopping cart. It requires a `customer_email`.

```json
{ "customer_email": "buyer@example.com" }
```

--------------------------------

### Checkout API - Create Checkout Session

Source: https://merchant.ygwyg.org/docs/index

JSON payload for initiating the checkout process. Requires `success_url` and `cancel_url` for redirecting the customer after checkout.

```json
{
  "success_url": "https://site.com/thanks",
  "cancel_url": "https://site.com/cart"
}
```

--------------------------------

### Checkout API

Source: https://merchant.ygwyg.org/docs/index

Endpoint for initiating the checkout process and creating a Stripe Checkout session.

```APIDOC
## POST /v1/carts/:id/checkout

### Description
Reserves inventory for the items in the cart and creates a Stripe Checkout session. Redirects the customer to the Stripe Checkout URL.

### Method
POST

### Endpoint
/v1/carts/:id/checkout

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the cart to checkout.

#### Query Parameters

#### Request Body
- **success_url** (string) - Required - The URL to redirect to after successful payment.
- **cancel_url** (string) - Required - The URL to redirect to if the user cancels the checkout.

### Request Example
```json
{
  "success_url": "https://site.com/thanks",
  "cancel_url": "https://site.com/cart"
}
```

### Response
#### Success Response (200)
- **checkout_url** (string) - The URL for the Stripe Checkout session.
- **stripe_checkout_session_id** (string) - The ID of the Stripe Checkout session.

#### Response Example
```json
{
  "checkout_url": "https://checkout.stripe.com/...",
  "stripe_checkout_session_id": "cs_..."
}
```
```

--------------------------------

### Connect Stripe

Source: https://merchant.ygwyg.org/docs/llms

Establishes the Stripe integration by providing Stripe API keys. These keys are essential for processing payments and handling webhooks.

```APIDOC
## POST /v1/setup/stripe

### Description
Connects your Stripe account by providing API keys. Get keys from the Stripe Dashboard (https://dashboard.stripe.com/apikeys).

### Method
POST

### Endpoint
/v1/setup/stripe

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **stripe_secret_key** (string) - Required - Your Stripe secret API key.
- **stripe_webhook_secret** (string) - Required - Your Stripe webhook secret key.

### Request Example
```bash
curl -X POST https://your-domain.com/v1/setup/stripe \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "stripe_secret_key": "sk_test_...",
    "stripe_webhook_secret": "whsec_..."
  }'
```

### Response
#### Success Response (200)
(A success status code indicates the Stripe connection was established. Specific response body details are not provided.)
```

--------------------------------

### Create Test Order API Request

Source: https://merchant.ygwyg.org/docs/llms

Creates a test order without involving Stripe, useful for development. Requires Bearer token authentication and a JSON payload with customer email and items.

```http
POST /v1/orders/test
Authorization: Bearer sk_...
Content-Type: application/json

{
  "customer_email": "test@example.com",
  "items": [
    {"sku": "TEE-BLK-M", "qty": 1}
  ]
}
```

--------------------------------

### Refund Order

Source: https://merchant.ygwyg.org/docs/llms

Initiates a refund for a specific order. A partial refund can be issued by specifying the amount, or a full refund by omitting the amount.

```APIDOC
## POST /v1/orders/{id}/refund

### Description
Initiates a refund for a specific order. Omit `amount_cents` for a full refund.

### Method
POST

### Endpoint
/v1/orders/{id}/refund

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the order to refund.

#### Query Parameters
None

#### Request Body
- **amount_cents** (integer) - Optional - The amount to refund in cents. If omitted, the entire order amount will be refunded.

### Request Example
```bash
curl -X POST https://your-domain.com/v1/orders/uuid/refund \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 2999}'
```

### Response
#### Success Response (200)
- **stripe_refund_id** (string) - The ID of the refund transaction in Stripe.
- **status** (string) - The status of the refund (e.g., "succeeded").

#### Response Example
```json
{
  "stripe_refund_id": "re_...",
  "status": "succeeded"
}
```
```

--------------------------------

### Update Product API Endpoint

Source: https://merchant.ygwyg.org/docs/llms

PATCH request to update an existing product's details like title, description, or status. Accepts 'active' or 'draft' for status.

```http
PATCH /v1/products/{id}
Authorization: Bearer sk_...
Content-Type: application/json

{
  "title": "Updated Title",
  "description": "New description",
  "status": "draft"
}
```

--------------------------------

### Create Test Order

Source: https://merchant.ygwyg.org/docs/llms

Creates a test order without involving Stripe payment processing. This is useful for development and testing purposes.

```APIDOC
## POST /v1/orders/test

### Description
Creates a test order without Stripe payment. Useful for development and testing.

### Method
POST

### Endpoint
/v1/orders/test

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **customer_email** (string) - Required - The email address of the customer for the test order.
- **items** (array) - Required - An array of items to include in the test order.
  - **sku** (string) - Required - The SKU of the item.
  - **qty** (integer) - Required - The quantity of the item.

### Request Example
```bash
curl -X POST https://your-domain.com/v1/orders/test \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "test@example.com",
    "items": [
      {"sku": "TEE-BLK-M", "qty": 1}
    ]
  }'
```

### Response
(The response structure for creating a test order is not explicitly detailed in the provided text, but it would typically return the created order object or its ID.)
```

--------------------------------

### Inventory Management API

Source: https://merchant.ygwyg.org/docs/index

Endpoints for managing inventory levels for products.

```APIDOC
## GET /v1/inventory

### Description
Returns inventory for all SKUs. Can be filtered by SKU.

### Method
GET

### Endpoint
/v1/inventory

### Parameters
#### Path Parameters

#### Query Parameters
- **sku** (string) - Optional - Filter inventory by a specific SKU.

#### Request Body

### Request Example
```
GET /v1/inventory?sku=TEE-BLK-M
```

### Response
#### Success Response (200)
- **items** (array) - List of inventory records.
  - **sku** (string) - The SKU of the item.
  - **on_hand** (integer) - Total stock available.
  - **reserved** (integer) - Stock reserved for pending checkouts.
  - **available** (integer) - Stock available for sale.

#### Response Example
```json
{
  "items": [
    {
      "sku": "TEE-BLK-M",
      "on_hand": 100,
      "reserved": 5,
      "available": 95
    }
  ]
}
```

## POST /v1/inventory/:sku/adjust

### Description
Adjusts the stock level for a given SKU.

### Method
POST

### Endpoint
/v1/inventory/:sku/adjust

### Parameters
#### Path Parameters
- **sku** (string) - Required - The SKU of the inventory to adjust.

#### Query Parameters

#### Request Body
- **delta** (integer) - Required - The amount to add (positive) or remove (negative) from stock.
- **reason** (string) - Required - The reason for the adjustment (e.g., `restock`, `correction`, `damaged`, `return`).

### Request Example
```json
{
  "delta": 50,
  "reason": "restock"
}
```

### Response
#### Success Response (200)
- **sku** (string) - The SKU that was adjusted.
- **on_hand** (integer) - The new total stock on hand.
- **reserved** (integer) - The current reserved stock.
- **available** (integer) - The new available stock.

#### Response Example
```json
{
  "sku": "TEE-BLK-M",
  "on_hand": 150,
  "reserved": 5,
  "available": 145
}
```
```

--------------------------------

### Complete Checkout Flow

Source: https://merchant.ygwyg.org/docs/llms

Details the steps involved in completing a customer checkout, from cart creation to order fulfillment via Stripe webhooks.

```APIDOC
## Complete Checkout Flow

### Description
This outlines the typical sequence of API calls and external interactions to complete a customer checkout process.

### Steps
1.  **Create Cart**: Initialize a shopping cart for a customer.
    ```bash
    # Example: Create cart
    curl -X POST http://localhost:8787/v1/carts \
      -H "Authorization: Bearer pk_..." \
      -H "Content-Type: application/json" \
      -d '{"customer_email":"buyer@example.com"}'
    ```
2.  **Add Items**: Add products to the created cart.
    ```bash
    # Example: Add items to cart
    curl -X POST http://localhost:8787/v1/carts/{cart_id}/items \
      -H "Authorization: Bearer pk_..." \
      -H "Content-Type: application/json" \
      -d '{"items":[{"sku":"TEE-BLK-M","qty":1}]}'
    ```
3.  **Checkout**: Initiate the checkout process, generating a Stripe checkout URL.
    ```bash
    # Example: Checkout
    curl -X POST http://localhost:8787/v1/carts/{cart_id}/checkout \
      -H "Authorization: Bearer pk_..." \
      -H "Content-Type: application/json" \
      -d '{"success_url":"https://site.com/thanks","cancel_url":"https://site.com/cart"}'
    ```
4.  **Redirect Customer**: Redirect the customer to the `checkout_url` provided by the checkout endpoint.
5.  **Customer Payment**: The customer completes the payment on the Stripe-hosted page.
6.  **Stripe Webhook**: Stripe sends a `checkout.session.completed` event to your configured webhook endpoint.
7.  **Order Creation & Inventory Deduction**: The webhook handler processes the event, creates an order, and automatically deducts inventory.
```

--------------------------------

### Create Cart API Endpoint

Source: https://merchant.ygwyg.org/docs/llms

POST request to create a new shopping cart. Requires customer email. Carts expire after 30 minutes.

```http
POST /v1/carts
Authorization: Bearer pk_... (or sk_...)
Content-Type: application/json

{
  "customer_email": "buyer@example.com"
}
```

--------------------------------

### Upload Image

Source: https://merchant.ygwyg.org/docs/llms

Uploads an image file. Supports JPEG, PNG, WebP, and GIF formats, with a maximum file size of 5MB.

```APIDOC
## POST /v1/images

### Description
Uploads an image file. Max size: 5MB. Formats: jpeg, png, webp, gif.

### Method
POST

### Endpoint
/v1/images

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file** (file) - Required - The image file to upload.

### Request Example
```bash
curl -X POST https://your-domain.com/v1/images \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/your/image.jpg"
```

### Response
#### Success Response (200)
- **url** (string) - The URL where the uploaded image can be accessed.
- **key** (string) - The unique key or path to the stored image.

#### Response Example
```json
{
  "url": "https://your-domain.com/storage/uuid.jpg",
  "key": "store_id/uuid.jpg"
}
```
```

--------------------------------

### List Orders

Source: https://merchant.ygwyg.org/docs/llms

Retrieves a list of all orders associated with the merchant account. Supports filtering and pagination through query parameters (not detailed here).

```APIDOC
## GET /v1/orders

### Description
Retrieves a list of orders.

### Method
GET

### Endpoint
/v1/orders

### Parameters
#### Query Parameters
(Specific query parameters for filtering and pagination are not detailed in the provided text.)

#### Request Body
None

### Request Example
```bash
curl -X GET https://your-domain.com/v1/orders \
  -H "Authorization: Bearer sk_..."
```

### Response
#### Success Response (200)
- **items** (array) - An array of order objects.
  - **id** (string) - Unique identifier for the order.
  - **number** (string) - Order number.
  - **status** (string) - Current status of the order (e.g., "paid").
  - **customer_email** (string) - Email of the customer.
  - **amounts** (object) - Contains pricing details.
    - **subtotal_cents** (integer) - Subtotal amount in cents.
    - **tax_cents** (integer) - Tax amount in cents.
    - **shipping_cents** (integer) - Shipping cost in cents.
    - **total_cents** (integer) - Total amount in cents.
    - **currency** (string) - Currency code (e.g., "USD").
  - **items** (array) - Array of items included in the order.
  - **created_at** (string) - Timestamp when the order was created.

#### Response Example
```json
{
  "items": [
    {
      "id": "uuid",
      "number": "ORD-00001",
      "status": "paid",
      "customer_email": "buyer@example.com",
      "amounts": {
        "subtotal_cents": 5998,
        "tax_cents": 0,
        "shipping_cents": 0,
        "total_cents": 5998,
        "currency": "USD"
      },
      "items": [...],
      "created_at": "2025-01-01T12:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Order API - Create Test Order

Source: https://merchant.ygwyg.org/docs/index

JSON payload for creating a test order without involving Stripe, useful for development and testing purposes. Requires `customer_email` and `items`.

```json
{
  "customer_email": "test@example.com",
  "items": [{ "sku": "TEE-BLK-M", "qty": 1 }]
}
```

--------------------------------

### List Orders API Request

Source: https://merchant.ygwyg.org/docs/llms

Retrieves a list of orders. Requires Bearer token authentication.

```http
GET /v1/orders
Authorization: Bearer sk_...
```

--------------------------------

### Checkout Cart API Endpoint

Source: https://merchant.ygwyg.org/docs/llms

POST request to initiate the checkout process for a cart. Requires success and cancel URLs for Stripe integration.

```http
POST /v1/carts/{id}/checkout
Authorization: Bearer pk_... (or sk_...)
Content-Type: application/json

{
  "success_url": "https://yoursite.com/thanks?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://yoursite.com/cart"
}
```

--------------------------------

### Common Error Codes

Source: https://merchant.ygwyg.org/docs/index

A list of common error codes, their corresponding HTTP status codes, and descriptions.

```APIDOC
## Common Error Codes

### Description
This table outlines common error codes, their HTTP status codes, and descriptions.

### Error Codes Table
| Code                     | Status | Description                   |
|--------------------------|--------|-------------------------------|
| `unauthorized`           | 401    | Invalid API key               |
| `forbidden`              | 403    | Missing permission            |
| `not_found`              | 404    | Resource not found            |
| `invalid_request`        | 400    | Bad request data              |
| `conflict`               | 409    | Duplicate SKU, cart not open  |
| `insufficient_inventory` | 409    | Not enough stock              |
```

--------------------------------

### Order API - Refund Order

Source: https://merchant.ygwyg.org/docs/index

JSON payload for initiating a refund for an order. Specify `amount_cents` for a partial refund; omit for a full refund.

```json
{ "amount_cents": 2999 }
```