> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fusioncore.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> fusionCore REST API — purpose, authentication, base URL, versioning

The fusionCore REST API is an unmanaged-package Salesforce Apex REST surface that exposes external integration endpoints for order management and subscription operations. It wraps the fusionCore Commerce (`FCORE_PAY`) and Subscriptions (`FCORE_MEM`) service-layer events in a stable HTTP contract so that external systems can drive order creation, line-item maintenance, renewal generation, and subscription cancellation without writing Apex.

## Welcome

This API exposes five operations across four resource families:

* **Order** — create a new Order (`POST /v1/order`).
* **Order Item** — add (`POST /v1/order-item`) or remove (`DELETE /v1/order-item/{id}`) line items on an existing Order.
* **Order Renewal** — generate renewal orders from sets of Purchase Activities (`POST /v1/orderRenewal`).
* **Subscription Cancellation** — cancel one or more subscription renewals (`POST /v1/subscription/cancel`).

It runs inside a Salesforce org as Apex REST resources. Typical consumers are external billing systems, AMS / portal integrations, and back-office automations that need to reach into fusionCore from outside Salesforce.

## Base URL

Salesforce Apex REST endpoints live under your org's My Domain:

```
https://{instance}.my.salesforce.com/services/apexrest/{path}
```

Replace `{instance}` with your org's My Domain prefix (for example, `acme-dev` for `https://acme-dev.my.salesforce.com`). Sandboxes use the standard `<domain>.sandbox.my.salesforce.com` form. The `{path}` portion is the operation path documented for each endpoint (for example, `/v1/order`).

## Authentication

Every endpoint requires a Salesforce session-scoped bearer token in the `Authorization` header:

```
Authorization: Bearer <SESSION_ID_OR_ACCESS_TOKEN>
```

You can obtain a token in either of the standard ways:

* **OAuth 2.0** — recommended for server-to-server and user-delegated integrations. See Salesforce's [OAuth 2.0 authorization flows](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_flows.htm).
* **SOAP login API** — returns a session id directly. See Salesforce's [SOAP `login()` reference](https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_login.htm).

The user (or connected app's run-as user) must have the Apex class permissions and CRUD access required to create / delete the underlying records (Order, OrderItem, etc.).

## Versioning

The path prefix `/v1/` is the API major version. Backwards-compatible additions are made within `/v1/`; any breaking change introduces a new major version (`/v2/`) and the previous version is supported in parallel for a deprecation window.

## Error handling

All endpoints return JSON responses. Standard HTTP status codes are used:

| Status | Meaning                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| 200    | Success (typically for delete and idempotent operations).                               |
| 201    | Resource created (POSTs that produce a new record).                                     |
| 400    | Validation error — missing required fields, malformed JSON, or business-rule violation. |
| 404    | Referenced record (Product, Order Item, etc.) not found.                                |
| 500    | Unexpected server-side error.                                                           |

Error responses share a common envelope:

```json theme={null}
{
  "success": false,
  "errors": ["businessUnitId is required"]
}
```

Successful responses always include `"success": true` and may include operation-specific fields (for example, `id` and `uuid` on `POST /v1/order`).