Working with customer self-service

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Intro

Use case description of how to use the customer self-service collection to display customer profile data and process customer-initiated data changes via the Open API.

This collection follows an amendment model:

• GET endpoints return current data state and expose any pending change request.
• POST endpoints submit new amendment requests per data domain.
• DELETE endpoint cancels an existing amendment before it is processed.

Each GET response also includes an amendmentConfigurationStatus that controls whether changes go through a verification queue or are applied directly.

Relevant Endpoints

• GET customer's contact data
• POST create contact data amendment
• GET customer's address data
• POST create address data amendment
• GET customer's master data
• POST create master data amendment
• GET customer's payment data
• POST create payment data amendment
• DELETE withdraw customer's amendment

Customer self-service

The customer self-service collection enables partners to build profile maintenance flows for members while keeping data changes transparent and auditable.

Core behavior:

• Changes are submitted as domain-specific amendments, not as direct updates.
• Each GET response includes amendmentConfigurationStatus: CHANGES_WITHOUT_VERIFICATION (applied instantly), CHANGES_REQUIRE_VERIFICATION (queued for studio approval), or READ (domain is view-only and cannot be amended).
• Only one active amendment can exist per data domain at a time. Attempting to create a second amendment while one is pending returns an error.
• Each GET response includes a pendingAmendment object when a change request is already in progress. The id field in that object is required to withdraw the amendment.
• Payment amendments may require a customer signature (requireSignature: true), passed as signature.base64SvgSignature in the POST request.

Recommended use cases:

• Member profile maintenance in web or app
• Contact and address correction flows
• Payment method change requests
• Self-service with optional studio-side review

Display and amendment flow

1. Retrieve current data

Use the GET endpoint for each domain before rendering an edit screen.

Use this to:

• prefill user-facing forms with current values
• read amendmentConfigurationStatus to determine whether changes apply immediately or require review
• detect a pendingAmendment and surface it to the user before allowing new submissions

2. Check amendment configuration status

Before rendering a change form, evaluate amendmentConfigurationStatus:

• CHANGES_WITHOUT_VERIFICATION — changes apply immediately on POST
• CHANGES_REQUIRE_VERIFICATION — changes go into a studio task queue; show the user that approval is pending
• READ — the domain is read-only; do not offer an edit option

3. Submit an amendment

When a customer confirms their changes, POST to the corresponding domain endpoint.

Use this to:

• submit changes for one domain at a time
• store the returned id (amendment proposal id) for subsequent withdraw calls if needed
• show domain-level feedback: immediate confirmation or pending state depending on configuration

Best practice:

• submit only one amendment per domain at a time
• explicitly handle the 409 conflict case for when a pending amendment already exists

4. Withdraw an amendment

If a pending amendment needs to be cancelled before it is processed, use DELETE withdraw customer's amendment with the customerId and amendmentId (the id returned from the POST response).

Use this to:

• let users undo a submitted change request
• clear the pending state so a corrected amendment can be submitted

5. Refresh data after mutations

After any POST or DELETE, re-fetch the relevant GET endpoint to keep frontend state in sync.

Complete workflow examples

Note: The payload examples below are integration-oriented drafts. Validate all field names and structures against the current OpenAPI schema before publishing or implementation.

Example 1: Update contact data

Scenario: Customer changes their email address.

1. GET customer's contact data
2. Check amendmentConfigurationStatus
3. Show prefilled edit form
4. POST create contact data amendment
5. Re-fetch GET customer's contact data

Example POST request payload (illustrative):

{
  "email": "new-email@example.com",
  "phonePrivate": "+49 00000000",
  "phonePrivateMobile": "+49 00000000000",
  "phoneBusiness": "+49 00000000",
  "phoneBusinessMobile": "+49 00000000000"
}

Example POST response shape (illustrative):

{
  "id": 4521,
  "email": "new-email@example.com",
  "phonePrivate": "+49 00000000",
  "phonePrivateMobile": "+49 00000000000",
  "phoneBusiness": "+49 00000000",
  "phoneBusinessMobile": "+49 00000000000"
}

Example 2: Submit address change, then withdraw

Scenario: Customer submits a new address but notices a typo and cancels before it is processed.

1. GET customer's address data
2. POST create address data amendment
3. Store returned id (e.g., 7834)
4. Customer requests cancellation
5. DELETE withdraw customer's amendment (amendmentId: 7834)
6. Re-fetch GET customer's address data

Example POST request payload (illustrative):

{
  "street": "Am Bahnhof",
  "houseNumber": "90",
  "zipCode": "12133",
  "city": "Munich",
  "countryCode": "DE"
}

Example POST response shape (illustrative):

{
  "id": 7834,
  "street": "Am Bahnhof",
  "houseNumber": "90",
  "zipCode": "12133",
  "city": "Munich",
  "countryCode": "DE"
}

DELETE withdraw returns HTTP 200 with no response body.

Example 3: Update payment data with signature

Scenario: Customer updates their bank account. The studio requires a customer signature.

1. GET customer's payment data
2. Check requireSignature: true in response
3. Present signature capture in UI
4. POST create payment data amendment with IBAN, BIC, and base64 SVG signature
5. Re-fetch GET customer's payment data

Example POST request payload (illustrative):

{
  "accountHolder": "Sven Hannawald",
  "bankName": "Deutsche Bank",
  "iban": "DE91 1000 0000 0123 4567 89",
  "bic": "DEUTDEFFXXX",
  "signature": {
    "base64SvgSignature": "<base64-encoded SVG>"
  }
}

Example POST response shape (illustrative):

{
  "id": 3301,
  "accountHolder": "Sven Hannawald",
  "bankName": "Deutsche Bank",
  "iban": "DE91 1000 0000 0123 4567 89",
  "bic": "DEUTDEFFXXX",
  "requireSignature": true
}

Common integration challenges

• Ignoring amendmentConfigurationStatus: Always read this field before rendering an edit option. Submitting to a READ domain returns an error.
• Missing pending amendment check: If pendingAmendment is present on GET, block new submissions for that domain and surface the pending state to the user.
• Concurrent amendment conflict: Attempting a second POST while one is pending returns 409. Handle this explicitly rather than letting it surface as a generic error.
• No post-mutation refresh: Always re-fetch the relevant GET endpoint after POST or DELETE to prevent stale form state.
• Skipping signature handling: For payment amendments where requireSignature is true, the POST request must include signature.base64SvgSignature. Missing this field will cause a validation failure.
• Cross-domain saves: Combining changes from multiple domains in a single UI action complicates error handling. Submit one amendment domain per action.

Customer self-service webhook events

For event-driven synchronization, subscribe to the relevant customer update events. These are triggered when a pending amendment is approved or rejected by studio staff, or when data is updated directly, and can be used to keep local profile state in sync.

Event reference:

• Event types