Skip to main content

Managing your Customers

This API allows Suppliers to add a price tier, reference ID, preferred location and credit limits to customer Organizations. When associated with a price tier, all users in the Organization will see the according prices when browsing your products and building a cart. Additionally, any reference ID you provide will be included in all future order payloads placed by their users. Credit limits and availability will be shown to the user during checkout on the OpenSolar website and should be kept current to ensure accuracy.

Authentication​

You must include a valid bearer token in the Authorization header to authenticate your request. Refer to Using Bearer Tokens for guidance.

Endpoint​

MethodEndpointDescription
POST/api/orgs/:org_id/org_seller_integrationsUpdate Customer fields
  • :org_id: your OpenSolar Organization ID

Customer Fields​

FieldTypeDescription
price_tierstringThe key for the appropriate price tier. The tier must already exist — create it under Prices before you assign it here.
seller_org_referencestringYour reference for the customer within your tooling. This will be included in order payloads for easy matching to customer.
trade_credit_totalintegerThe maximum credit limit you provide to the customer.
trade_credit_availableintegerThe currently available credit value for the customer.
preferred_locationstringThe key for the default stock location the customer will interface with. Default for delivery origin and collection location. The location must already exist — create it under Stock Locations before you assign it here.

Updating Customer Fields​

The body of your POST request must include the org_id as per the below schema. You can obtain the customer org_id via either the Customer Email Matching endpoint or User Connected events.

Request Body​

[
  {
    "org_id": 1,
    "price_tier": "tier_platinum2",
    "preferred_location": "birmingham_warehouse"
  },
  {
    "org_id": 4,
    "price_tier": "tier_platinum2",
    "seller_org_reference": "customer123",
    "trade_credit_available": 10000,
    "trade_credit_total": 2300,
    "preferred_location": "portland_warehouse"
  }
]

Note that seller_org_reference, trade_credit_available, trade_credit_total and preferred_location are optional.

Remove Price Tier from Customer​

If you wish to remove the price tier from an Organization, you can do so with the below schema. Note that this will default the Organization to your public price, which the users can continue to view and purchase at on the OpenSolar site.

Request Body​

[
  {
    "org_id": 10,
    "price_tier": null
  }
]

API Responses​

Success Response​

All Organizations synced successfully.

Code: 200 OK

Content:

{
  "message": "All orgs synced successfully.",
  "data": {
    "success_total": 2
  }
}

Partial Sync Response​

Some of the Organizations could not be updated.

Code: 206 Partial Content

{
  "message": "Sync failure: The following orgs could not be synced.",
  "data": {
    "success_total": 1,
    "failed_total": 1,
    "failed_synced_orgs": [
      {
        "org_id": 1,
        "invalid_price_tier": "tierplatinum2",
        "reason": "price tier does not exist"
      }
    ]
  }
}

Error Sync Response​

None of the Organizations could be updated.

Code: 400 Bad Request

{
  "message": "Sync failure: The following orgs could not be synced.",
  "data": {
    "success_total": 0,
    "failed_total": 1,
    "failed_synced_orgs": [
      {
        "org_id": 1,
        "invalid_price_tier": "tierplatinum2",
        "reason": "price tier does not exist"
      }
    ]
  }
}

Additional Notes​

  • The price_tier and preferred_location values must match the key of an existing price tier (Prices) or stock location (Stock Locations) exactly.
  • Each org_id must refer to a valid customer Organization that is eligible to be linked.
  • trade_credit_available cannot be greater than the trade_credit_total