{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/magicline/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["partial"]},"type":"markdown"},"seo":{"title":"Sport Alliance Developer Portal","description":"Portal for Partners","siteUrl":"https://developer.sportalliance.com","keywords":"sportalliance sport alliance fitness sports","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"__idx":0,"id":"working-with-customer-self-service"},"children":["Working with customer self-service"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"__idx":1,"id":"intro"},"children":["Intro"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This collection follows an amendment model:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["GET endpoints return current data state and expose any pending change request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["POST endpoints submit new amendment requests per data domain."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["DELETE endpoint cancels an existing amendment before it is processed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each GET response also includes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amendmentConfigurationStatus"]}," that controls whether changes go through a verification queue or are applied directly."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"__idx":2,"id":"relevant-endpoints"},"children":["Relevant Endpoints"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../openapi/openapi/customers-self-service/getCustomerContactData"},"children":["GET customer's contact data"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../openapi/openapi/customers-self-service/createCustomerContactDataAmendment"},"children":["POST create contact data amendment"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../openapi/openapi/customers-self-service/getCustomerAddressData"},"children":["GET customer's address data"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../openapi/openapi/customers-self-service/createCustomerAddressDataAmendment"},"children":["POST create address data amendment"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../openapi/openapi/customers-self-service/getCustomerMasterData"},"children":["GET customer's master data"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../openapi/openapi/customers-self-service/createCustomerMasterDataAmendment"},"children":["POST create master data amendment"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../openapi/openapi/customers-self-service/getCustomerPaymentData"},"children":["GET customer's payment data"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../openapi/openapi/customers-self-service/createCustomerPaymentDataAmendment"},"children":["POST create payment data amendment"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../openapi/openapi/customers-self-service/withdrawAmendment"},"children":["DELETE withdraw customer's amendment"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"__idx":3,"id":"customer-self-service"},"children":["Customer self-service"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The customer self-service collection enables partners to build profile maintenance flows for members while keeping data changes transparent and auditable."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Core behavior:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Changes are submitted as domain-specific amendments, not as direct updates."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each GET response includes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amendmentConfigurationStatus"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHANGES_WITHOUT_VERIFICATION"]}," (applied instantly), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHANGES_REQUIRE_VERIFICATION"]}," (queued for studio approval), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READ"]}," (domain is view-only and cannot be amended)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each GET response includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pendingAmendment"]}," object when a change request is already in progress. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," field in that object is required to withdraw the amendment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Payment amendments may require a customer signature (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requireSignature: true"]},"), passed as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature.base64SvgSignature"]}," in the POST request."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recommended use cases:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Member profile maintenance in web or app"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Contact and address correction flows"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Payment method change requests"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Self-service with optional studio-side review"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"__idx":4,"id":"display-and-amendment-flow"},"children":["Display and amendment flow"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"__idx":5,"id":"1.-retrieve-current-data"},"children":["1. Retrieve current data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the GET endpoint for each domain before rendering an edit screen."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["prefill user-facing forms with current values"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amendmentConfigurationStatus"]}," to determine whether changes apply immediately or require review"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["detect a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pendingAmendment"]}," and surface it to the user before allowing new submissions"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"__idx":6,"id":"2.-check-amendment-configuration-status"},"children":["2. Check amendment configuration status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before rendering a change form, evaluate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amendmentConfigurationStatus"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHANGES_WITHOUT_VERIFICATION"]}," — changes apply immediately on POST"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHANGES_REQUIRE_VERIFICATION"]}," — changes go into a studio task queue; show the user that approval is pending"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READ"]}," — the domain is read-only; do not offer an edit option"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"__idx":7,"id":"3.-submit-an-amendment"},"children":["3. Submit an amendment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a customer confirms their changes, POST to the corresponding domain endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["submit changes for one domain at a time"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["store the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (amendment proposal id) for subsequent withdraw calls if needed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["show domain-level feedback: immediate confirmation or pending state depending on configuration"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best practice:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["submit only one amendment per domain at a time"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["explicitly handle the 409 conflict case for when a pending amendment already exists"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"__idx":8,"id":"4.-withdraw-an-amendment"},"children":["4. Withdraw an amendment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a pending amendment needs to be cancelled before it is processed, use DELETE withdraw customer's amendment with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amendmentId"]}," (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," returned from the POST response)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["let users undo a submitted change request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["clear the pending state so a corrected amendment can be submitted"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"__idx":9,"id":"5.-refresh-data-after-mutations"},"children":["5. Refresh data after mutations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After any POST or DELETE, re-fetch the relevant GET endpoint to keep frontend state in sync."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"__idx":10,"id":"complete-workflow-examples"},"children":["Complete workflow examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note: The payload examples below are integration-oriented drafts. Validate all field names and structures against the current OpenAPI schema before publishing or implementation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"__idx":11,"id":"example-1-update-contact-data"},"children":["Example 1: Update contact data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Scenario: Customer changes their email address."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["GET customer's contact data"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amendmentConfigurationStatus"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show prefilled edit form"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["POST create contact data amendment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Re-fetch GET customer's contact data"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example POST request payload (illustrative):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"email\": \"new-email@example.com\",\n  \"phonePrivate\": \"+49 00000000\",\n  \"phonePrivateMobile\": \"+49 00000000000\",\n  \"phoneBusiness\": \"+49 00000000\",\n  \"phoneBusinessMobile\": \"+49 00000000000\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example POST response shape (illustrative):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": 4521,\n  \"email\": \"new-email@example.com\",\n  \"phonePrivate\": \"+49 00000000\",\n  \"phonePrivateMobile\": \"+49 00000000000\",\n  \"phoneBusiness\": \"+49 00000000\",\n  \"phoneBusinessMobile\": \"+49 00000000000\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"__idx":12,"id":"example-2-submit-address-change-then-withdraw"},"children":["Example 2: Submit address change, then withdraw"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Scenario: Customer submits a new address but notices a typo and cancels before it is processed."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["GET customer's address data"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["POST create address data amendment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["7834"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer requests cancellation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["DELETE withdraw customer's amendment (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amendmentId: 7834"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Re-fetch GET customer's address data"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example POST request payload (illustrative):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"street\": \"Am Bahnhof\",\n  \"houseNumber\": \"90\",\n  \"zipCode\": \"12133\",\n  \"city\": \"Munich\",\n  \"countryCode\": \"DE\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example POST response shape (illustrative):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": 7834,\n  \"street\": \"Am Bahnhof\",\n  \"houseNumber\": \"90\",\n  \"zipCode\": \"12133\",\n  \"city\": \"Munich\",\n  \"countryCode\": \"DE\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["DELETE withdraw returns HTTP 200 with no response body."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"__idx":13,"id":"example-3-update-payment-data-with-signature"},"children":["Example 3: Update payment data with signature"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Scenario: Customer updates their bank account. The studio requires a customer signature."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["GET customer's payment data"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requireSignature: true"]}," in response"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Present signature capture in UI"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["POST create payment data amendment with IBAN, BIC, and base64 SVG signature"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Re-fetch GET customer's payment data"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example POST request payload (illustrative):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"accountHolder\": \"Sven Hannawald\",\n  \"bankName\": \"Deutsche Bank\",\n  \"iban\": \"DE91 1000 0000 0123 4567 89\",\n  \"bic\": \"DEUTDEFFXXX\",\n  \"signature\": {\n    \"base64SvgSignature\": \"<base64-encoded SVG>\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example POST response shape (illustrative):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": 3301,\n  \"accountHolder\": \"Sven Hannawald\",\n  \"bankName\": \"Deutsche Bank\",\n  \"iban\": \"DE91 1000 0000 0123 4567 89\",\n  \"bic\": \"DEUTDEFFXXX\",\n  \"requireSignature\": true\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"__idx":14,"id":"common-integration-challenges"},"children":["Common integration challenges"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ignoring ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amendmentConfigurationStatus"]},": Always read this field before rendering an edit option. Submitting to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READ"]}," domain returns an error."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Missing pending amendment check: If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pendingAmendment"]}," is present on GET, block new submissions for that domain and surface the pending state to the user."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["No post-mutation refresh: Always re-fetch the relevant GET endpoint after POST or DELETE to prevent stale form state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Skipping signature handling: For payment amendments where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requireSignature"]}," is true, the POST request must include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature.base64SvgSignature"]},". Missing this field will cause a validation failure."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cross-domain saves: Combining changes from multiple domains in a single UI action complicates error handling. Submit one amendment domain per action."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"__idx":15,"id":"customer-self-service-webhook-events"},"children":["Customer self-service webhook events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Event reference:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"../webhooks/event-types/"},"children":["Event types"]}]}]}]},"headings":[{"value":"Working with customer self-service","id":"working-with-customer-self-service","depth":1},{"value":"Intro","id":"intro","depth":2},{"value":"Relevant Endpoints","id":"relevant-endpoints","depth":2},{"value":"Customer self-service","id":"customer-self-service","depth":2},{"value":"Display and amendment flow","id":"display-and-amendment-flow","depth":2},{"value":"1. Retrieve current data","id":"1.-retrieve-current-data","depth":3},{"value":"2. Check amendment configuration status","id":"2.-check-amendment-configuration-status","depth":3},{"value":"3. Submit an amendment","id":"3.-submit-an-amendment","depth":3},{"value":"4. Withdraw an amendment","id":"4.-withdraw-an-amendment","depth":3},{"value":"5. Refresh data after mutations","id":"5.-refresh-data-after-mutations","depth":3},{"value":"Complete workflow examples","id":"complete-workflow-examples","depth":2},{"value":"Example 1: Update contact data","id":"example-1-update-contact-data","depth":3},{"value":"Example 2: Submit address change, then withdraw","id":"example-2-submit-address-change-then-withdraw","depth":3},{"value":"Example 3: Update payment data with signature","id":"example-3-update-payment-data-with-signature","depth":3},{"value":"Common integration challenges","id":"common-integration-challenges","depth":2},{"value":"Customer self-service webhook events","id":"customer-self-service-webhook-events","depth":2}],"frontmatter":{"seo":{"title":""}},"lastModified":"2026-03-20T08:05:35.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/magicline/usecases/customers-self-service","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}