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

# Writing Data

The Trackstar API enables you to write data into your end users' connected accounts.

We have done the heavy lifting to unify the `body` of each action across integrations, so you can write data in a consistent way across all of them. For each resource, we call this the "Base Schema". See the [Create Order Base Schema](/api-reference/wms-api/orders/post#base-schema) as an example.

However, the required and optional fields may vary depending on the integration you are writing to. Additionally, some integrations may require a field that is unique to them. To handle these cases, we have also included each integration's schema in the reference. See [Extensiv's Create Order Schema](/api-reference/wms-api/orders/post#extensiv-3-pl-central) for an example.

On the API side, we have created an endpoint that will return the required and optional fields for a given entity in a given integration.

## The /integrations endpoint

The [GET integrations](/api-reference/mgmt/integrations) endpoint returns information on our supported integrations. The required, optional, and integration-specific fields for each write operation are returned in the response.

```json theme={null}
{
  "data": [
    {
      "integration_name": "Some WMS",
      "write_operations": [
        {
          "action": "create_order",
          "url": "POST /wms/orders",
          "required_base_schema_fields": [
            "line_items.product_id",
            "line_items.quantity"
          ],
          "optional_base_schema_fields": [
            "order_number",
            "line_items",
            "channel",
            "trading_partner"
          ],
          "integration_specific_fields": {
            "properties": {
              "warehouse_id": {
                "title": "warehouse_id",
                "type": "string",
                "description": "The warehouse this order will shipped from.",
                "example": "",
                "enum": [
                  "warehouse_1",
                  "warehouse_2"
                ]
              }
            },
            "type": "object",
            "required_fields": [
              "warehouse_id"
            ]
          }
        }
      ],
      "available_actions": [
        "get_inventory",
        "get_products",
        "create_order",
      ]
    }
  ]
}
```

## Example Create Order Request

Based on the response from the `/integrations` endpoint, the required and optional fields to create an order in the `Some WMS` integration are as follows:

| Field                   | Description                     | Type   | Required |
| ----------------------- | ------------------------------- | ------ | -------- |
| line\_items.product\_id | The product ID of the line item | string | Yes      |
| line\_items.quantity    | The quantity of the line item   | number | Yes      |
| order\_number           | The order number                | string | No       |
| line\_items             | The line items                  | array  | No       |
| channel                 | The channel                     | string | No       |
| trading\_partner        | The trading partner             | string | No       |
| warehouse\_id           | The warehouse ID                | string | Yes      |

Let's send in all of the fields for this request:

```bash theme={null}
curl -X POST https://production.trackstarhq.com/wms/orders \
  -H "x-trackstar-api-key: <x-trackstar-api-key>" \
  -H "x-trackstar-access-token: <x-trackstar-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "product_id": "123",
        "quantity": 2
      }
    ],
    "order_number": "1234",
    "channel": "Retail",
    "trading_partner": "Target",
    "warehouse_id": "warehouse_1"
  }'
```

And that's it! You have successfully created an order in your end user's connected system.

## Non Nullable Fields

All fields in the write body are **non-nullable**. Put another way, you cannot send a `null` or empty string value for any field. This includes null string literals such as `"null"`, `"none"`, or any similar variation.

For example, `order_number` and `reference_id` are optional fields. Sending in the following request will result in a 422 error response:

```bash theme={null}
  curl -X POST https://production.trackstarhq.com/wms/orders \
  -H "x-trackstar-api-key: <x-trackstar-api-key>" \
  -H "x-trackstar-access-token: <x-trackstar-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "order_number": null,
    "reference_id": "",
    "line_items": [
      {
        "product_id": "123",
        "quantity": 2
      }
    ]
  }'
```

Instead, you should omit the fields from the request like so:

```bash theme={null}
  curl -X POST https://production.trackstarhq.com/wms/orders \
  -H "x-trackstar-api-key: <x-trackstar-api-key>" \
  -H "x-trackstar-access-token: <x-trackstar-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "product_id": "123",
        "quantity": 2
      }
    ]
  }'
```