Customer Endpoint

Endpoint

Customers

Customer management with support for multiple addresses.

Overview

OperationMethodEndpointScope
ExportGET/xpanel/xoport/export/json/customerscustomers:read
ImportPOST/xpanel/xoport/import/json/customerscustomers:write
UpdatePUT/xpanel/xoport/import/json/customerscustomers:write
DeleteDELETE/xpanel/xoport/delete/json/customerscustomers:delete

Export (GET)

Query Parameters

ParameterTypeDescription
customers_idintExport individual customers
customers_email_addressstringFilter by email
customers_group_idintFilter by customer group
limitintMax. number
offsetintStart position

Response fields

  • customers_id, customers_email_address
  • customers_firstname, customers_lastname
  • customers_telephone, customers_fax
  • customers_group_id - Customer group
  • addresses[] - All of the customer's addresses

Address fields

  • entry_company, entry_firstname, entry_lastname
  • entry_street_address, entry_postcode, entry_city
  • entry_country_id, entry_zone_id

As of v2.122.1, the export no longer includes password data: customers_password, customers_password_request, customers_password_request_time, and customers_hash have been removed without replacement; in the customer record, iban and bic have also been removed.

Import (POST/PUT)

Sample Request

curl -X POST "https://shop.de/xpanel/xoport/import/json/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customers",
    "data": [{
      "customers_email_address": "max@example.de",
      "customers_firstname": "Max",
      "customers_lastname": "Mustermann",
      "customers_group_id": 1,
      "addresses": [{
        "entry_company": "Musterfirma GmbH",
        "entry_street_address": "Musterstr. 1",
        "entry_postcode": "12345",
        "entry_city": "Musterstadt",
        "entry_country_id": 81
      }]
    }]
  }'

Partially Change Address (PUT)

Corrected in v2.122.2

To modify an existing address, use addresses[] with address_book_id. Only the values specified in the object are written: Missing or null fields remain unchanged, while "" clears a field. The country and zone are updated only if you include them. Specifying a new country without entry_zone_id sets the zone to 0.

curl -X PUT "https://shop.de/xpanel/xoport/import/json/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customers",
    "data": [{
      "customers_id": 42,
      "addresses": [{
        "address_book_id": 905,
        "entry_street_address": "Neue Straße 99",
        "entry_country": "AT"
      }]
    }]
  }'
Shops prior to v2.122.2: In these cases, an address update without a country would reset the country to the shop’s country (STORE_COUNTRY) and the zone to 0. For these shops, therefore, always include the country as an ISO code in entry_country or as entry_country_id.
  • If the country is unknown, warnings[] reports the warning ADDRESS_COUNTRY. During the update, the stored country remains unchanged; the shop country is assigned a new address.
  • Values that are too long are truncated to the column length based on the number of characters, with the warning “ ADDRESS_TRUNCATED.”
  • If the object contains only “ _set_default ” or “ _set_billing,” the default or billing address is set without changing any address fields.

Customer Discounts (discounts[])

New in v2.57.0

Use the discounts[] field to manage the customer’s discounts (the “Discounts” field in Customer Management, table customers_discount). A discount line means: x% discount on category N.

Sample Request

curl -X PUT "https://shop.de/xpanel/xoport/import/json/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customers",
    "data": [{
      "customers_id_extern": "20050",
      "discounts": [
        {"category_id": 0, "value": 10},
        {"category_id": 22, "value": "12,5", "subcategories": 0, "special": 1}
      ]
    }]
  }'

Fields per discount row

FieldTypeDefaultDescription
category_idint–Category ID; 0 = top level – together with subcategories=1, the discount applies to the entire product range
valuedecimalRequiredPercentage value; decimal point allowed. Values > 100 are capped at 100; values ≤ 0 are skipped
subcategories0/11Discount also applies to subcategories
qpb0/10Discount also applies to tiered pricing
option0/10Discount also applies to attribute surcharges
special0/10Discount also applies to special offers

Replace-on-present semantics

  • discounts If entries exist → the customer’s entire list of discounts is replaced
  • "discounts": [] (empty) → all of the customer’s discounts are removed
  • Field is missing → discounts remain unchanged (existing integrations do not affect this)

The customer’s internal activation flag is automatically updated—the discounts take effect immediately in the store. The same semantics also apply to the XML customer import (<discounts> node).

Export: The Customers export (GET) returns discounts as raw lines—round-trip capable.

WaWi Addressing

New in v2.57.0

  • customers_id_extern (WaWi customer number) and customers_group_id are now writable in the JSON import; customers_group_id is validated against existing customer groups.
  • PUT can now address the customer even without an email address via customers_id or customers_id_extern (pure discount/master data maintenance). customers_id_extern must be unique.
  • POST still requires an email address and a physical address.

Delete (DELETE)

curl -X DELETE "https://shop.de/xpanel/xoport/delete/json/customers?customers_id=123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Note: GDPR-relevant data! Please observe retention periods for orders.