Skip to main content

Expanding Resources

The Propeller REST API provides a powerful resource expansion mechanism that allows you to retrieve related data in a single API call. This feature helps optimize performance by reducing the number of requests needed to gather complete information about resources and their relationships.

Overview​

Resource expansion is available on all GET requests and allows you to include related objects directly in the response. Instead of making multiple API calls to fetch related data, you can use the expands parameter to retrieve everything you need in one request.

How It Works​

When you use the expands parameter, the API will include the specified related resources directly in the response, rather than just providing their IDs. This is particularly useful for:

  • Performance Optimization: Reduce API calls and network overhead
  • Data Consistency: Ensure related data is retrieved at the same point in time
  • Simplified Integration: Get complete object graphs in single requests
  • Efficient Data Loading: Load all necessary data for UI components

Available Expand Parameters​

Expand ParameterDescriptionUse CaseExample
sourcesExpands resource with source objectsExternal system referencesGET /v2/products/456?expands=sources
parentExpands parent resourceHierarchical relationshipsGET /v2/contacts/123?expands=parent
translationExpands translated fields for all languagesMulti-language contentGET /v2/products/456?expands=translation
order_itemsExpands order with all order itemsComplete order detailsGET /v2/orders/123?expands=order_items
addressesExpands orders with address informationShipping and billingGET /v2/orders/123?expands=addresses
clusterConfigExpands clusters with configurationCluster settingsGET /v2/clusters/789?expands=clusterConfig
optionsExpands clusters with their optionsProduct variant managementGET /v2/clusters/789?expands=options
productsExpands clusters/pricesheets with productsProduct relationshipsGET /v2/clusters/789?expands=products
defaultProductExpands cluster/option with default productProduct variant detailsGET /v2/clusters/789?expands=defaultProduct
surchargesExpands products with surchargesAdditional feesGET /v2/products/789?expands=surcharges
inventoryBalanceExpands all inventory resources for productsStock and availabilityGET /v2/products/456?expands=inventoryBalance
note

The expand parameters listed above represent only a subset of all available expansion options in the Propeller REST API. For a complete list of all available expand parameters for each specific entity, please refer to the individual entity documentation pages.

Detailed Expand Parameters​

Source Information​

  • Parameter: sources
  • Applies to: All resources (Products, Categories, Companies, Customers, Contacts, Users, Usergroups, Clusters)
  • Description: Retrieves external system references and source information
GET /v2/products/456?expands=sources

Response includes:

  • External system identifiers
  • Source system metadata
  • Import/export tracking information

Parent Relationships​

  • Parameter: parent
  • Applies to: Companies, Customers, Contacts, Users, Clusters
  • Description: Retrieves parent resource in hierarchical structures
GET /v2/contacts/123?expands=parent

Response includes:

  • Parent company information
  • Hierarchical structure details
  • Inherited settings and permissions

Multi-Language Translations​

  • Parameter: translation
  • Applies to: Products, Categories, Clusters
  • Description: Retrieves content in all available languages
GET /v2/products/456?expands=translation

Response includes:

  • Product information in all configured languages
  • Names, descriptions, and metadata for each language
  • Default language plus all translations

Order Items Expansion​

  • Parameter: order_items
  • Applies to: Orders
  • Description: Retrieves all items within an order
GET /v2/orders/123?expands=order_items

Response includes:

  • Complete order information
  • All order items with quantities, prices, and totals
  • Item-level discounts and taxes

Address Information​

  • Parameter: addresses
  • Applies to: Orders
  • Description: Retrieves shipping and billing addresses
GET /v2/orders/123?expands=addresses

Response includes:

  • Shipping addresses
  • Billing addresses
  • Address validation and formatting

Cluster Configuration​

  • Parameter: clusterConfig
  • Applies to: Clusters
  • Description: Retrieves configuration settings for clusters
GET /v2/clusters/789?expands=clusterConfig

Response includes:

  • Cluster configuration settings
  • Behavior and display options
  • Custom configuration parameters

Cluster Options​

  • Parameter: options
  • Applies to: Clusters
  • Description: Retrieves all options within a product cluster
GET /v2/clusters/789?expands=options

Response includes:

  • All cluster options with details
  • Option-specific pricing and availability
  • Variant selection data

Cluster Products​

  • Parameter: products
  • Applies to: Clusters
  • Description: Retrieves related products for clusters
GET /v2/clusters/789?expands=products

Response includes:

  • All products in the cluster
  • Product specifications and pricing
  • Relationship metadata

Default Product for Clusters​

  • Parameter: defaultProduct
  • Applies to: Clusters, Options
  • Description: Retrieves the default product for product clusters
GET /v2/clusters/789?expands=defaultProduct

Response includes:

  • Cluster information with default product details
  • Product specifications and pricing
  • Variant selection logic

Surcharges​

  • Parameter: surcharges
  • Applies to: Products
  • Description: Retrieves additional fees and surcharges
GET /v2/products/789?expands=surcharges

Response includes:

  • Additional fees and charges
  • Surcharge calculations
  • Fee application rules

Inventory Information​

  • Parameter: inventoryBalance
  • Applies to: Products
  • Description: Retrieves current stock levels and availability
GET /v2/products/456?expands=inventoryBalance

Response includes:

  • Current stock quantities
  • Available inventory across warehouses
  • Backorder information
  • Stock status indicators

Advanced Usage Patterns​

Multiple Expansions​

Combine multiple expansions in a single request:

GET /v2/products/123?expands=sources,parent,translation

Performance Considerations​

Best Practices​

  • Use Sparingly: Only expand resources you actually need
  • Combine Expansions: Use multiple expansions in single requests when possible
  • Monitor Response Size: Large expansions can increase response time

Performance Impact​

  • Response Size: Expanded responses are larger and take longer to transfer
  • Processing Time: Server processing time increases with expansions
  • Memory Usage: Both client and server use more memory
  • Network Latency: Larger responses take longer to transmit

Resource expansion provides a powerful way to optimize API usage and retrieve complete data graphs efficiently. Use it strategically to balance performance with data completeness.