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. 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 integration.

The /write-info endpoint

The GET Write Info endpoint returns information on our supported integrations in standard OpenAPI format. The required and optional fields are denoted in the response. If you choose to pass in the optional access token, you will also get any connection-specific information you might need about writing data. Here’s an example from hitting /integrations/wms/ongoing (truncated for just Returns):

{
  "openapi": "3.1.0",
  "paths": {
    "/wms/returns": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatewmsReturnOngoingSchema"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Create WMS Return output"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreatewmsReturnOngoingSchema": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "The ID of the order that the return is associated with. Can be passed into the [Order](/api-reference/wms-api/orders/get-item) endpoint for more details.",
            "example": "order_id"
          },
          "warehouse_id": {
            "type": "string",
            "description": "The ID of the warehouse receiving the return. Can be passed into the [Warehouse](/api-reference/wms-api/warehouses/get-item) endpoint for more details.",
            "example": "warehouse"
          },
          "line_items": {
            "type": "array",
            "description": "A list of inventory items included in the return.",
            "example": [
              {
                "sku": "TEST-SKU",
                "expected_quantity": 1,
                "return_cause": null
              }
            ],
            "items": {
              "$ref": "#/components/schemas/WmsReturnWriteLineItemongoing"
            }
          },
          "return_number": {
            "type": "string",
            "description": "Return number"
          },
          "tracking_number": {
            "type": "string",
            "description": ""
          },
          "tracking_url": {
            "type": "string",
            "description": ""
          },
          "trackstar_tags": {
            "type": [
              "array",
              "null"
            ],
            "description": "A list of custom tags associated with the resource. A tag can be either a string or a dictionary with one key-value pair.",
            "example": [
              "tag1",
              "tag2",
              {
                "tag3": "value3"
              }
            ],
            "items": {}
          }
        },
        "required": [
          "line_items",
          "order_id",
          "return_number"
        ],
        "additionalProperties": false,
        "title": "CreatewmsReturnOngoingSchema"
      },
      "WmsReturnWriteLineItemongoing": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": ""
          },
          "expected_quantity": {
            "type": "integer",
            "description": "",
            "example": 0
          },
          "return_cause": {
            "$ref": "#/components/schemas/ReturnCause"
          }
        },
        "required": [
          "expected_quantity",
          "sku"
        ],
        "additionalProperties": false,
        "title": "WmsReturnWriteLineItemongoing"
      },
      "ReturnCause": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "1",
              "13",
              "3"
            ],
            "description": "The reason code for this return. Specific to your connection."
          },
          "return_reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "damaged",
              "wrong size",
              "no longer needed"
            ],
            "description": "The reason description for this return. Specific to your connection."
          }
        },
        "required": [
          "code"
        ],
        "additionalProperties": false,
        "title": "ReturnCause"
      }
    }
  }
}

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

Example Create Return Request

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

Field	Description	Type	Required
order_id	The order ID associated with the return	string	Yes
warehouse_id	The warehouse ID	string	No
line_items	The line items	array	Yes
line_items.sku	The SKU of the line item	string	Yes
line_items.expected_quantity	The expected quantity of the line item	number	Yes
line_items.return_cause	The reason for the line item’s return	object	No
line_items.return_cause.code	The reason code for the line item’s return. The values in this field are different for different connections - for this connection they are “1”, “13”, or “3”	string	Yes
line_items.return_cause.return_reason	The reason description for the line item’s return. The values in this field are different for different connections - for this connection they are “damaged”, “wrong size”, or “no longer needed”	string	No
return_number	The RMA number	string	Yes
tracking_number	The tracking number	string	No
tracking_url	The tracking URL	string	No
trackstar_tags	The Trackstar Tags	array	No

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

curl -X POST https://production.trackstarhq.com/wms/returns \
  -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_id": "1234",
    "warehouse_id": "warehouse_1",
    "line_items": [
      {
        "sku": "123",
        "expected_quantity": 2,
        "return_cause": {
	  "code": "1",
	  "return_reason": "damaged"
	}
      }
    ],
    "return_number": "rma_456",
    "tracking_number": "tracking_abc",
    "tracking_url": "https://fedex.com/tracking_abc",
    "trackstar_tags": ["tag1"]
  }'

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. You cannot send a null / "none" / empty string for any field. This is because nulls are ambiguous: they could mean you want the field blank on purpose, or maybe you’re just using a default. The underlying systems also disagree on what a null should do (some clear the field, some reject the request, some ignore it). Rather than guess and risk writing data you didn’t intend, we reject the request up front. If you don’t mean to set a field, leave it out of the body entirely. For example, tracking_number and tracking_url are optional fields. Sending in the following request will result in a 422 error response:

  curl -X POST https://production.trackstarhq.com/wms/returns \
  -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_id": "1234",
    "warehouse_id": "warehouse_1",
    "line_items": [
      {
        "sku": "123",
        "expected_quantity": 2,
        "return_cause": {
	  "code": "1",
	  "return_reason": "damaged"
	}
      }
    ],
    "return_number": "rma_456",
    "tracking_number": "",
    "tracking_url": null
  }'

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

  curl -X POST https://production.trackstarhq.com/wms/returns \
  -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_id": "1234",
    "warehouse_id": "warehouse_1",
    "line_items": [
      {
        "sku": "123",
        "expected_quantity": 2,
        "return_cause": {
	  "code": "1",
	  "return_reason": "damaged"
	}
      }
    ],
    "return_number": "rma_456"
  }'

Don’t See a Field You Need?

If the field is part of Trackstar’s schema (think order_number, carrier_name, expected_arrival_date etc) then reach out to us and we’ll gladly expose it for you if the integration allows.

Home

How-To Guides

Use Cases

The /write-info endpoint

Example Create Return Request

Non Nullable Fields

Don’t See a Field You Need?

​The /write-info endpoint

​Example Create Return Request

​Non Nullable Fields

​Don’t See a Field You Need?

The /write-info endpoint

Example Create Return Request

Non Nullable Fields

Don’t See a Field You Need?