> ## 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 V2 API

This reference is key for your comprehensive understanding of Commerce and, as such, essential for the successful use of our payment orchestration products.

Commerce APIs make use of RESTful conventions when possible and where it makes sense. All calls use the standard HTTP verbs to express access semantics, like `GET`, `POST`, `PATCH`, and `DELETE`. Other related conventions for our API can be found in the section below.

<Info>
  **Gated Endpoints**

  Labeled with:

  <Badge stroke icon="house-lock" color="orange">Gated Feature</Badge>

  Some of the features offered by Commerce are gated and require explicit activation.
  In order to get access you need to contact your account manager.
</Info>

<Info>
  **Beta Endpoints**

  Labeled with:

  <Badge stroke icon="wrench" color="blue">Beta Feature</Badge>

  Commerce offers various features as part of our beta release track. These features are experimental and subject to change or removal at any time. They may also have limited support and stability.

  By default, accounts do not have access to beta features unless explicitly subscribed to beta releases. If you would like to enable beta features, please contact your account manager for subscription options.
</Info>

## 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 supports API keys to authenticate requests.

The keys are passed in via the HTTP header `x-api-key`.

```bash theme={null}
curl --header 'X-API-Key: <SECRET>' \
  --request POST 'https://api.hellgate.io/...'
```

The keys 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

### API Versions

Commerce API will be updated regularly, to include new features and updates to existing ones. We package these changes into versions that can be addressed using a header field (`x-hellgate-version`).

If there is no version specified in the header, the most recent version is being used.

```bash theme={null}
curl --header 'x-hellgate-version: <SELECTED VERSION>' \
  --request POST 'https://api.hellgate.io/...'
```

Commerce sets the `x-hellgate-version` header on API responses, to tell the integrator which version is in use.

### 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>' ...
```

### Pagination

Endpoints that return lists of objects support cursor-based pagination requests. By default, Commerce returns up to 50 objects per API call. If the number of objects in a response from a support endpoint exceeds the default, then an integration can use pagination to request a specific set of the results and/or to limit the number of returned objects.

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

```json Response Sample theme={null}
{
  "current_page": 1,
  "page_size": 50,
  "total_items": 200,
  "total_pages": 4,
  "data": [...]
}
```

The single pages can be requested with 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.             |

### Request Errors

Commerce uses the standard errors to indicate the client errors on the gateway level.

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

    ```json theme={null}
    {
      "status": "the HTTP status code",
      "classifier": "the classifier of the error",
      "message": "interesting for humans..."
    }
    ```
  </Tab>

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

    ```json theme={null}
    {
      "status": "the HTTP status code",
      "classifier": "the classifier of the error",
      "message": "interesting for humans...",
      "validation_errors": [
        {
          "path": "a JSON path pointing to the wrong data",
          "message": "something interesting for humans..."
        }
      ]
    }
    ```
  </Tab>
</Tabs>

### Business Errors

The processing errors refer to the primary functions of Commerce and not necessarily to the related business logic. For example, a failed authorization due to insufficient funds will result in a 200 response, as the payment layer could successfully process the request (even though the business result is negative).