# API Endpoints

All endpoints are implemented as WooCommerce legacy API callbacks (`/?wc-api=<action>`). Global-e's back-end calls them over HTTPS using `POST` with a JSON body. Responses are JSON, sent via `Api::sendResponse()` which calls `die()` after `echo`.

GUID authentication (`MerchantGUID` in the request body) is validated by `Config::validGUID()` before any order mutation.

---

## Cart endpoints

### `GET|POST /?wc-api=pro-cart-info`

**Handler:** `GlobalePro::apiCartInfo()` → `Api\Cart::info()`

Called by Global-e's checkout overlay to retrieve the current cart contents.

**Authentication:** Identified as a Global-e REST call via `hash` query param or `CartId` in JSON body. Falls back to session-based auth (WooCommerce session cookie) when no hash is present.

**Response shape:**

```json
{
  "ProductsList": [ { "SKU": "…", "Quantity": 1, "ListPrice": 10.00, "SalePrice": 10.00, … } ],
  "DiscountsList": [ { "CouponCode": "…", "DiscountType": "percent", … } ],
  "IsFreeShipping": false,
  "FreeShippingCouponCode": null,
  "MerchantCartHash": "…",
  "ShippingOptionsList": [],
  "UserId": 42,
  "BillingDetails": { … },
  "ShippingDetails": { … }
}
```

**Error response:**

```json
{ "Error": true, "Code": 500, "Message": "…" }
```

---

### `POST /?wc-api=pro-cart-clear`

**Handler:** `GlobalePro::apiCartClear()` → `Api\Cart::clear()`

Empties the WooCommerce cart. Called by Global-e after a successful international order is placed.

**Response:**

```json
{ "Success": "true" }
```

---

## Order endpoints

All order endpoints validate `MerchantGUID` against the stored config. Requests without a valid GUID receive a `NotAuthorized` error response and processing stops.

### `POST /?wc-api=pro-order-create-update`

**Handler:** `GlobalePro::apiUpdateCreate()` → `Api\Order::create()`

Creates or updates a WooCommerce order from Global-e order data.

**Key request fields:** `MerchantGUID`, `OrderId` (Global-e), `MerchantOrderId`, `CartId`, `CustomerDetails`, `PaymentDetails`, `ProductsInformation`, `ShippingDetails`, `PriceSummary`.

**Response:**

```json
{
  "Success": "true",
  "InternalOrderId": 1001,
  "OrderId": "1001",
  "GlobalEOrderId": "GE-XXXXX"
}
```

---

### `POST /?wc-api=pro-order-payment`

**Handler:** `GlobalePro::apiOrderPayment()` → `Api\Order::payment()`

Marks an existing WooCommerce order as paid and updates payment metadata.

**Key request fields:** `MerchantGUID`, `OrderId`, `MerchantOrderId`, `PaymentDetails`.

**Side effect:** Logs the raw request on the order as `_globale_request_{timestamp}_order-payment`.

**Response:**

```json
{
  "Success": "true",
  "InternalOrderId": 1001,
  "OrderId": "1001",
  "GlobalEOrderId": "GE-XXXXX",
  "Message": "Order payment status updated"
}
```

---

### `POST /?wc-api=pro-order-status`

**Handler:** `GlobalePro::apiOrderStatus()` → `Api\Order::status()`

Updates the WooCommerce order status based on the Global-e `StatusCode`.

`Model\Order\Status::convertOrderStatus()` maps Global-e status codes to WooCommerce status slugs.

**Key request fields:** `MerchantGUID`, `OrderId`, `MerchantOrderId`, `StatusCode`.

**Response:**

```json
{
  "Success": "true",
  "InternalOrderId": 1001,
  "OrderId": "1001",
  "GlobalEOrderId": "GE-XXXXX",
  "Message": "Order status updated"
}
```

---

### `POST /?wc-api=pro-order-shipping`

**Handler:** `GlobalePro::apiOrderShipping()` → `Api\Order::shipping()`

Adds tracking information to an order from `InternationalDetails`.

**Key request fields:** `MerchantGUID`, `OrderId`, `MerchantOrderId`, `InternationalDetails` (contains carrier, tracking number, URL).

**Response:**

```json
{
  "Success": "true",
  "InternalOrderId": 1001,
  "OrderId": "1001",
  "GlobalEOrderId": "GE-XXXXX",
  "Message": "Shipping updated"
}
```

---

### `POST /?wc-api=pro-order-refund`

**Handler:** `GlobalePro::apiOrderRefund()` → `Api\Order::refund()`

Creates a WooCommerce refund for the specified order items or amount.

**Key request fields:** `MerchantGUID`, `OrderId`, `MerchantOrderId`, refund line items.

Refund logic lives in `Model\Order\Refund`. If `restock_refunded_products` is enabled in settings, inventory is restocked.

**Response:**

```json
{
  "Success": "true",
  "InternalOrderId": 1001,
  "OrderId": "1001",
  "GlobalEOrderId": "GE-XXXXX"
}
```

**Error handling:** Exceptions are caught, logged via `GCBWC::log()`, and returned as `Success: false`.

---

## Utility endpoints

### `GET /?wc-api=pro-plugin-info`

**Handler:** `GlobalePro::apiPluginInfo()` → `Api\PluginInfo::info()`

Returns plugin version and capability metadata. Used by Global-e's platform to detect supported features.

---

### `POST /?wc-api=pro-validate-cart-voucher`

**Handler:** `GlobalePro::apiValidateCartVoucher()` → `Api\ValidateCartVoucher::handle()`

Validates whether a coupon code can be applied to the current cart for a given country/currency context.

---

## Common request/response patterns

### GUID validation failure

```json
{
  "Success": "false",
  "Message": "Merchant GUID is not valid",
  "ErrorCode": "NotAuthorized",
  "MerchantOrderId": "…",
  "OrderId": "…"
}
```

### Missing POST body

```json
{
  "Success": "false",
  "Message": "something went wrong with POST parameters",
  "ErrorCode": "System"
}
```

### Request logging

`payment`, `status`, `shipping`, and `refund` endpoints store the raw JSON body as order meta with the key pattern `_globale_request_{unix_timestamp}_{method}`. This is always written even on successful responses; it serves as an audit trail.