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

# API Information

> Essential information for using the Commerce V1 API

This reference is essential for your comprehensive understanding of Commerce V1 and successful integration with our event-driven payment processing platform.

Commerce V1 APIs make use of RESTful conventions when possible. All calls use the standard HTTP verbs to express access semantics, like `GET`, `POST`, `PATCH`, and `DELETE`. The API is designed to work alongside [CloudEvents](/products/commerce/v1/eventing-reference/overview) for asynchronous service-to-service communication.

## JSON Conventions

* Resources are addressable by a UUIDv4 `id` property.
* Property names are always in `snake_case`.
* Commerce does not support empty strings. To unset a string value, use an explicit `null` value instead.
* Temporal data is encoded in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) strings.

## Authentication

Commerce V1 supports two authentication mechanisms to secure API access.

### API Keys

API keys are passed via the HTTP header `x-api-key` for standard operations.

```bash theme={null}
curl --header 'x-api-key: <SECRET>' \
  --request POST 'https://my-cluster-id.on-hellgate.cloud/...'
```

### Mutual TLS (mTLS)

For service-to-service communication, particularly with [extension services](/products/commerce/v1/integration/extensions/overview) and [processor integrations](/products/commerce/v1/integration/processors/processor-integration), Commerce V1 uses mutual TLS authentication over the event bridge.

Both authentication methods must be handled with care and kept secure. Never hardcode the API keys in your source code, but keep them solely on your backend systems.

## API Use

### Cluster-based Deployment

Commerce V1 is provided as a service of the Hellgate Cloud Platform implementing the [Composable Payment Architecture (CPA)](/platform/cpa). Each instance is accessible via a cluster-specific URL:

```
https://my-cluster-id.on-hellgate.cloud
```

Your specific cluster URL is provided during the onboarding process.

### Idempotency

To prevent your system from handling requests twice and thus, for example, charging a customer twice, Commerce supports idempotency on requests to the API.

The behavior is controlled via the header field `X-Idempotency-Key`.

```bash theme={null}
curl --header 'X-Idempotency-Key: <key>' \
  --request POST 'https://my-cluster-id.on-hellgate.cloud/...'
```

### Pagination

Endpoints that return lists of objects support pagination. Commerce V1 uses page-based pagination with the following query parameters:

| Parameter | Type      | Description                                             |
| :-------- | :-------- | :------------------------------------------------------ |
| `limit`   | `integer` | The maximum amount of objects to be returned on a page. |
| `page`    | `integer` | The requested number of the page to return.             |

If an endpoint supports pagination, the response body follows this structure:

```json Response Sample theme={null}
{
  "data": [...],
  "next_page": 2,
  "previous_page": null
}
```

### Request Errors

Commerce uses standard HTTP status codes to indicate client errors on the API level.

<Tabs>
  <Tab title="Invalid Requests - HTTP 4xx">
    The response payload for processing errors follows a standard format.

    ```json theme={null}
    {
      "code": 404,
      "classifier": "not_found",
      "message": "The requested resource was not found"
    }
    ```
  </Tab>

  <Tab title="Unprocessable Content - HTTP 422">
    The response payload for validation errors follows a standard format which includes validation details.

    ```json theme={null}
    {
      "code": 422,
      "classifier": "validation_error",
      "message": "The request could not be processed due to validation errors"
    }
    ```
  </Tab>
</Tabs>

## Event-Driven Architecture

Commerce V1 uses [CloudEvents 1.0](https://cloudevents.io/) for asynchronous communication between services. Many operations trigger events that are delivered via the mTLS-secured event bridge.

For detailed information about event types, payloads, and integration patterns, see the [Eventing Reference](/products/commerce/v1/eventing-reference/overview).

## Extension Services

Commerce V1 supports custom extension services that implement specific HTTP endpoints to extend payment processing flows. These services handle checkout experiences, 3-D Secure sessions, and SEPA mandate signatures.

For information about implementing extension services, see the [Extension Services](/products/commerce/v1/integration/extensions/overview) documentation.