Integration Best Practices

This page provides best practices and recommendations for integrating with the Solar Procurement Services API. It is intended to help developers design robust, efficient, and scalable integrations by correctly handling catalog data, product lifecycle, pricing, inventory, and order processing.

Handling the Full Product Catalog

When using the Solar Procurement Services API, you will receive the full product catalog, including products in all statuses.

This is by design and ensures that your system always has a complete and up-to-date view of the assortment, including any lifecycle changes. The API supports returning either the full catalog or only changes depending on how it is used.

To handle this correctly in your solution, it is important to actively use the product status as part of your integration logic.

The product statuses are:

  • 10 – Active

  • 11 – Active (stocked in another central warehouse)

  • 33 – Being phased out

  • 40 – Phased out

✅ Recommended approach

  • Compare with your previous data
    Retrieve the catalog and compare it with your previous dataset to identify changes in product status.

  • Handle phased-out products
    Products with status 40 should be removed or marked as inactive in your system.

  • Filter for downstream usage
    When requesting price and availability:

    • Include products with status 10, 11, 33

    • Exclude products with status 40

This ensures that your system remains aligned with Solar’s product assortment while avoiding processing products that are no longer available.

Use Delta Synchronization (lastChanged)

The product API supports retrieving only changed data using the lastChanged parameter.

If provided, only products changed after a specific timestamp will be returned. If omitted, the full product catalog is returned.

✅ Recommended approach

  • Use a full synchronization during initial load

  • Store the lastChanged timestamp per product

  • Use delta requests for ongoing synchronization

  • Combine with product status handling to detect lifecycle changes

This reduces data volume and improves performance.

Handle Pagination Correctly

Several endpoints (e.g. categories and products) use pagination with:

  • limit (maximum number of records)

  • nextPage token in the response

✅ Recommended approach

  • Always process responses until isLastPage = true

  • Use the nextPage value provided in the response for subsequent calls

  • Avoid assuming that all data is returned in a single request

This ensures completeness of data retrieval.

Authentication and Security

All API requests require authentication using a token retrieved via the authentication endpoint.

The API requires:

  • Authorization header (Bearer token)

  • Subscription key (header or query parameter)

✅ Recommended approach

  • Securely store credentials (ClientId and Secret)

  • Cache and reuse tokens until expiration

  • Handle token expiration gracefully by refreshing the token

Use Consistent Product Identification

The API supports multiple product identifiers such as:

For pricing and ordering, SAPMaterialNumber is the only identifier supported.

✅ Recommended approach

  • Internally standardize on SAPMaterialNumber

  • Convert other identifiers to SAPMaterialNumber where needed

  • Ensure consistency across catalog, pricing, inventory, and ordering

Requesting Price and Availability

Pricing and availability are not included in the catalog response and must be retrieved via dedicated endpoints:

  • /products/prices

  • /products/atp

✅ Recommended approach

  • Always request price and ATP (availability) as separate calls

  • Batch requests where possible (respect limits, e.g. max 500 products for pricing)

  • Filter out irrelevant products (e.g. status 40) before requesting

Location-Specific Inventory Handling

For certain countries, inventory requests require additional information:

  • Postal code is required when multiple warehouses exist (e.g. Sweden)

✅ Recommended approach

  • Always include postal code where applicable

  • Treat inventory as location-dependent

  • Ensure correct delivery context when querying availability

Respect Units, Multiples, and Quantities

Products include fields such as:

  • unit (sales unit)

  • baseUnitofMeasure

  • salesUnitofMeasure

  • multiplum (order increment)

  • minimumOrderQuantity

✅ Recommended approach

  • Validate order quantities against:

    • minimum order quantity

    • multiplum (order increment)

  • Use the correct sales unit when displaying or ordering.

Order Creation Best Practices

Orders are created via the /orders endpoint and require:

  • Account ID

  • Product identifiers (SAPMaterialNumber)

  • Quantity

  • Delivery information

✅ Recommended approach

  • Validate product data before placing orders

  • Ensure correct delivery address selection

  • Include customer references for traceability

  • Handle errors and confirmation responses properly

General Integration Principles

  • Design for eventual consistency (catalog vs price vs inventory)

  • Treat the catalog as the source of truth for product metadata

  • Use stateless API calls combined with local caching

  • Monitor for changes using lastChanged + status transitions

  • Implement retry logic and error handling for resilience