GraphQL

The returns.cloud GraphQL API is the primary interface for integrating external systems with returns.cloud. It allows you to read, create, and update data across the post-purchase process, from product and Sales Order data to returns, parcels, tracking information, and warehouse processes.

The API is designed for developers integrating ERP systems, shop platforms, middleware, warehouse systems, or other applications with returns.cloud.

GraphQL differs from traditional REST APIs in one important way: instead of providing many fixed endpoints with predefined response structures, GraphQL exposes a typed data model and lets the client describe exactly which data it needs.

This is particularly useful for returns.cloud because the underlying data is highly connected. A Sales Order can contain Sales Order Items and Sales Order Parcels, reference a Consumer and a Sales Channel, and be connected to one or more Return Orders. GraphQL allows these relationships to be queried as part of the same request. The returns.cloud schema exposes these relationships directly.

How GraphQL works

A GraphQL API is built around a schema. The schema describes the available entities, fields, relationships, input objects, enums, queries, and mutations.

There are two main operations you will use when working with returns.cloud:

• Queries read data.
• Mutations create or modify data.

Unlike REST, where you might request a complete resource from an endpoint such as /orders/123, a GraphQL query contains a selection set. The selection set defines the exact fields that should be returned.

For example, when retrieving Sales Orders, you might only need the order number, status, and tracking information:

query {
  salesOrders(limit: 10) {
    totalCount
    data {
      ... on SalesOrder {
        externalId
        number
        status
        salesOrderParcels {
          trackingNumber
          trackingStatus {
            statusLevel1
            statusLevel2
          }
        }
      }
    }
  }
}

The server returns only the fields requested by the query.

If another integration also needs the Consumer, Sales Order Items, or associated Return Orders, those fields can be added to the same query without requiring a different endpoint. The schema exposes, for example, salesOrderItems, salesOrderParcels, consumer, salesChannel, and returnOrders as relationships of a Sales Order.

This makes the API flexible without requiring a separate API operation for every possible combination of data.

Why returns.cloud uses GraphQL

Request exactly the data you need

GraphQL lets the client decide which fields should be returned.

An integration that only needs a tracking number and the current tracking status does not need to retrieve the complete parcel, order, customer, and item structure. Another integration can request considerably more information using the same API.

This helps keep integrations focused on the data they actually process.

Work with related data in one request

returns.cloud contains strongly related entities such as:

Sales Order → Sales Order Items → Sales Order Parcels → Return Order → Return Order Parcels

These relationships are part of the data model rather than being represented by isolated API endpoints.

GraphQL allows you to traverse these relationships as part of a query. For example, a Sales Order query can include its parcels, while a Return Order can include its Sales Orders, Return Order Items, Return Order Parcels, Consumer, and other related information.

This can significantly reduce the amount of integration logic required to assemble related information.

A strongly typed and discoverable API

GraphQL schemas define which fields exist, which values they accept, which fields are required, which enums are available, and which objects are related.

For example, the returns.cloud schema defines dedicated types such as SalesOrder, SalesOrderParcel, ReturnOrder, ReturnOrderParcel, Item, ItemVariation, Warehouse, and CarrierContract. It also defines input objects and enums for operations such as filtering and status handling.

This provides developers with an explicit contract for the data exchanged with returns.cloud.

Schema introspection

The returns.cloud API supports the standard GraphQL Introspection Query.

Introspection allows development tools to inspect the GraphQL schema programmatically and discover:

• available queries and mutations
• types and fields
• field arguments
• input objects
• enum values
• relationships between types
• required and optional values
• descriptions and deprecations

This means that the API can describe its own structure.

For every integration, we provide several tools for working with the GraphQL schema:

• GraphiQL for interactive schema exploration and executing queries and mutations.
• SpectaQL for generated API reference documentation.
• GraphQL Voyager for visualizing the schema and the relationships between its types.

These tools use the GraphQL schema and its introspection capabilities to help you understand and work with the API.

See API Exploration for details.

Well suited for AI-assisted development

The combination of a structured query language, a typed schema, introspection, and machine-readable field definitions also makes GraphQL particularly suitable for AI-assisted development.

Instead of relying only on manually written examples, an AI coding tool can work with the actual schema to understand available entities, fields, input types, enums, and relationships. This can make it easier to generate initial queries and mutations, explore unfamiliar parts of the API, or adapt an existing request to include additional information.

The schema remains the source of truth. AI-generated requests should therefore always be validated against the schema and tested before being used in production.

Typical integration scenarios

The GraphQL API can be used throughout the returns.cloud data lifecycle. Common integration scenarios include:

• Product Catalogue – synchronize products, categories, Item Variations, attributes, and related catalogue information.
• Sales Order Import – create and update Sales Orders including Consumers, Sales Order Items, and Sales Order Parcels.
• Return Order Export – retrieve Return Orders and their items, selected actions, return reasons, parcels, refund information, and associated Sales Orders.
• Outbound parcel tracking – exchange tracking information for Sales Order Parcels.
• Return parcel tracking – retrieve tracking information and status histories for Return Order Parcels.
• Warehouse processes – announce incoming returns and exchange warehouse-related information such as Warehouse Feedback.

The schema directly provides queries for entities including categories, items, Item Variations, Sales Orders, Sales Order Parcels, Return Orders, Return Order Parcels, warehouses, Return Reasons, and Carrier Contracts.

Queries, filters, and pagination

List queries commonly support filters, pagination, and, where applicable, sorting.

For example, Sales Orders can be filtered using a SalesOrderFilter, paginated using offset and limit, and sorted using orderBy. Return Orders and Return Order Parcels provide similar mechanisms.

Filters use typed comparison operators. Depending on the field type, these include operators such as:

eq, neq, in, lt, lte, gt, gte, isNull, and isNotNull.

This makes it possible to build queries such as incremental exports based on createdAt or updatedAt, lookups based on external identifiers, or searches for specific tracking numbers.

See Filter for the complete filtering concept and examples.

Processing data in bulk

The API is designed to also support integrations that process larger amounts of data.

Up to 100 records can be processed in one request, both when reading data and when using mutations that accept multiple records. List queries expose a maximum limit of 100 records per page.

This allows integrations to process data in batches instead of issuing an individual HTTP request for every entity. For example, an ERP synchronization can retrieve Sales Orders in pages of up to 100 records, while supported mutations can process multiple input records together.

See Bulk Operations for recommendations on batching and processing larger datasets.

References between entities

Many objects in returns.cloud reference other entities.

For integrations, these relationships cannot always be handled using internal returns.cloud IDs. External systems therefore frequently work with attributes such as externalId, sourceExternalId, or technical identifiers.

For example, the schema describes externalId as the identifier of an entity in the system using the API and uses it for querying, updating, and referencing entities.

Understanding how references are resolved is particularly important when importing nested structures such as Sales Orders containing Items, Parcels, Warehouses, Subcustomers, or Item Variations.

See Reference Attribute Handling before implementing larger imports.

Entity states

Sales Orders, Return Orders, parcels, warehouse processes, and other entities can move through different states.

These states are represented by typed enums in the GraphQL schema. For example, Return Orders expose states such as created, in_process, finished, transit, warehouse, processed, closed, and completed.

An entity's state can affect which operations are possible and how an integration should react to subsequent updates.

See Entity Status Model for the state concepts relevant to integrations.

Exploring your integration API

You do not need to learn the complete schema before starting development.

Each integration provides access to tools that allow you to explore the API directly:

GraphiQL is the interactive development environment. Use it to browse the schema, construct queries and mutations, inspect available arguments, and execute requests against your integration.

SpectaQL provides generated reference documentation based on the GraphQL schema and is useful when looking up available types, fields, inputs, and descriptions.

Because returns.cloud supports introspection, these tools can work directly with the schema exposed by your integration. The underlying schema defines separate query and mutation roots and exposes the available types and relationships programmatically.

See API Exploration for instructions on using both tools.

Continue with the API documentation

After this introduction, we recommend continuing with the following topics in order:

Authentication – learn how requests to the API are authenticated.

API Exploration – use GraphiQL, SpectaQL, and GraphQL introspection to explore your schema.

Filter – retrieve exactly the entities relevant to your integration.

Bulk Operations – process larger datasets efficiently.

Entity Status Model – understand how entity states affect integrations.

Reference Attribute Handling – learn how entities are identified and referenced across systems.

Use cases & example requests – start with practical requests for common integration scenarios.