Writing Data

The Trackstar API enables you to write data into your end users’ connected accounts. Unlike reads, writes don’t involve syncing: when you perform a write operation (such as creating or updating a resource via POST or PUT), Trackstar forwards that request directly to the underlying integration in real time. We respond immediately with the success or error status from the integration, including any error messages or validation feedback provided by the integration itself. This ensures transparency and helps with rapid debugging and resolution when issues arise. 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 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 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 endpoint returns information on our supported integrations. The required, optional, and integration-specific fields for each write operation are returned in the response.

{
  "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",
      ]
    }
  ]
}

Write endpoints your org has disabled return a 403 (e.g. create_order is disabled for this connection) without reaching the integration.

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:

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:

  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:

  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
      }
    ]
  }'

Home

How-To Guides

Use Cases

The /integrations endpoint

Example Create Order Request

Non Nullable Fields

​The /integrations endpoint

​Example Create Order Request

​Non Nullable Fields

The /integrations endpoint

Example Create Order Request

Non Nullable Fields