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

# Requests and responses

> REST conventions, versioning, headers, query parameters, request bodies, and data formats of the SimpleSell API.

The SimpleSell API follows REST conventions. Each resource, such as a parcel, has its own URL, and standard HTTP methods work on it:

| Method | Purpose | Example |
| - | - | - |
| `GET` | Retrieve a resource or list resources | `GET /parcels/{id}` |
| `POST` | Create a resource | `POST /parcels` |
| `PATCH` | Update parts of a resource | `PATCH /parcels/{id}` |
| `DELETE` | Delete a resource | `DELETE /parcels/{id}` |

Actions that go beyond these methods, such as processing or cancelling a parcel, are `POST` requests to a sub-path of the resource, for example `POST /parcels/{id}/process`.

The API uses HTTP status codes to indicate success or failure. See [Error handling](/api/v1/error-handling).

## Versioning

The API version is part of the [base URL](/api/v1/introduction#base-url). The current version is `v1`.

Within `v1`, we only make backward-compatible changes, such as new endpoints, new optional parameters, new response fields, or new values for fields like `source`. Make sure your integration ignores fields and values it doesn't know.

Breaking changes only come with a new version, such as `v2`. We announce new versions in advance and keep the previous version available for a transition period.

## Headers

| Header | Value |
| - | - |
| `Authorization` | `Bearer YOUR_API_TOKEN`. Required for every request. See [Authentication](/api/v1/authentication). |
| `Content-Type` | `application/json`. Required for requests with a body. |

The API always responds with JSON, except for document downloads. You don't need to send an `Accept` header.

## Query parameters

Boolean query parameters, such as `print` or `apply_products`, only accept `true` or `false`. Other values, such as `1` or `yes`, return `400 Bad Request`.

List endpoints share conventions for sorting and filtering. See [Pagination, sorting, and filtering](/api/v1/pagination-sorting-filtering).

## Request bodies

Requests that create or update resources take a JSON body. The reference of each endpoint, such as [Create a parcel](/api/v1/parcels/create-a-parcel), lists the fields it accepts.

* The API ignores fields it doesn't know. Check the field names carefully, because a misspelled field is ignored without an error.
* To remove the value of a field that can be empty, send `null`. The reference marks these fields as nullable.

When you update a resource with `PATCH`, the API only changes the top-level fields you send:

* Fields you omit keep their current value.
* Nested objects and arrays, such as `receiver` or `items`, are replaced as a whole. To change a single receiver field, send the complete `receiver` object.

## Responses

Responses wrap the requested data in a `data` object:

```json theme={null}
{
  "data": {
    "id": "3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59",
    "order_number": "10042"
  }
}
```

List endpoints return an array in `data` and pagination links in `links`. Document downloads return PDF files.

Every response also contains an `X-Request-ID` header. Include it when you contact support about a request. See [Contact support](/api/v1/error-handling#contact-support).

## Data formats

| Type | Format | Example |
| - | - | - |
| IDs | UUID | `"3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59"` |
| Timestamps | `YYYY-MM-DDTHH:MM:SSZ` in UTC | `"2026-10-18T09:41:12Z"` |
| Weights | Kilograms, as a decimal string with up to 3 decimal places | `"1.250"` |
| Dimensions | Centimeters, as a decimal string with up to 1 decimal place | `"30.5"` |
| Prices | Decimal string with up to 2 decimal places | `"19.90"` |
| Countries | ISO 3166-1 alpha-2 code | `"DE"` |
| Currencies | ISO 4217 code | `"EUR"` |

### Timestamps

The API only accepts timestamps in exactly this format: `2026-10-18T09:41:12Z`. Timestamps with fractional seconds or a time zone offset, such as `2026-10-18T11:41:12+02:00`, are rejected. Convert local times to UTC before you send them.

### Decimal values

Prices, weights, and dimensions are strings, not numbers. This avoids rounding errors with floating-point numbers. Use a dot as the decimal separator.

Responses always contain the full number of decimal places. For example, if you send a weight of `"1.2"`, the API returns `"1.200"`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.