From 2d4a010a1dc96d5ac6dadd5442c3e88d48e79fe1 Mon Sep 17 00:00:00 2001 From: Dawood Ali Date: Wed, 9 Sep 2026 17:33:20 -0600 Subject: [PATCH] Rename public partner API identifier --- public/search-index.json | 14 +++++++------- .../api/partner-api-customer-attribution-token.md | 4 ++-- .../data/api/partner-api-integration-flow.md | 14 +++++++------- .../data/api/partner-api-order-manage-link.md | 4 ++-- src/docs-app/data/api/partner-api-overview.md | 8 ++++---- src/docs-app/data/api/partner-api-users.md | 14 +++++++------- src/docs-app/data/api/partner-api-webhooks.md | 6 +++--- src/docs-app/data/partnerApiExamplesMap.ts | 8 ++++---- src/docs-app/data/seoData.ts | 2 +- .../data/webhooks/01-webhooks-introduction.md | 2 +- 10 files changed, 38 insertions(+), 38 deletions(-) diff --git a/public/search-index.json b/public/search-index.json index 4650c78..267355b 100644 --- a/public/search-index.json +++ b/public/search-index.json @@ -57,37 +57,37 @@ "id": "/api/partner-api-customer-attribution-token", "title": "Create checkout attribution", "path": "/api/partner-api-customer-attribution-token", - "content": "Create a short-lived token that connects a Showpass checkout to a customer in your system.\n``http\nPOST /api/partner/customer-attribution-token/\n`\nCall this endpoint from your backend immediately before opening the Ticket Purchase Widget. The customer must first be connected with Sync a customer with Showpass.\nAuthenticate the request with the HMAC scheme in the Partner API overview.\n`json\n{\n \"partner_user_id\": \"customer-42\"\n}\n`\nThe endpoint returns 201:\n`json\n{\n \"customer_attribution_token\": \"opaque-token\",\n \"customer_attribution_token_expires_in_seconds\": 3600\n}\n`\nPass the token directly to the purchase widget:\n`javascript\nshowpass.tickets.eventPurchaseWidget(selectedEvent.slug, {\n \"customer_attribution_token\": customerAttributionToken\n});\n`\nShowpass validates the token when it creates the checkout basket, then carries the resolved Partner customer relationship onto the completed order.\n- It is short-lived checkout context for one Partner customer.\n- It is valid for one hour and can be used by supported checkout flows during that period.\n- It does not authenticate the customer or create a logged-in Showpass session.\n- It does not replace the buyer information collected during checkout.\n- It is not a Partner API credential, bearer token, or refresh token.\nThe raw value is returned only in this response; Showpass stores its SHA-256 hash. Do not persist it as a long-lived customer credential or include it in logs.\n- 400 Bad Request: partner_user_id is missing or invalid.\n- 403 Forbidden: authentication failed or checkout attribution is not enabled for this Partner integration.\n- 409 Conflict`: the Partner customer does not exist or is inactive." + "content": "Create a short-lived token that connects a Showpass checkout to a customer in your system.\n``http\nPOST /api/partner/customer-attribution-token/\n`\nCall this endpoint from your backend immediately before opening the Ticket Purchase Widget. The customer must first be connected with Sync a customer with Showpass.\nAuthenticate the request with the HMAC scheme in the Partner API overview.\n`json\n{\n \"partner_external_user_id\": \"customer-42\"\n}\n`\nThe endpoint returns 201:\n`json\n{\n \"customer_attribution_token\": \"opaque-token\",\n \"customer_attribution_token_expires_in_seconds\": 3600\n}\n`\nPass the token directly to the purchase widget:\n`javascript\nshowpass.tickets.eventPurchaseWidget(selectedEvent.slug, {\n \"customer_attribution_token\": customerAttributionToken\n});\n`\nShowpass validates the token when it creates the checkout basket, then carries the resolved Partner customer relationship onto the completed order.\n- It is short-lived checkout context for one Partner customer.\n- It is valid for one hour and can be used by supported checkout flows during that period.\n- It does not authenticate the customer or create a logged-in Showpass session.\n- It does not replace the buyer information collected during checkout.\n- It is not a Partner API credential, bearer token, or refresh token.\nThe raw value is returned only in this response; Showpass stores its SHA-256 hash. Do not persist it as a long-lived customer credential or include it in logs.\n- 400 Bad Request: partner_external_user_id is missing or invalid.\n- 403 Forbidden: authentication failed or checkout attribution is not enabled for this Partner integration.\n- 409 Conflict`: the Partner customer does not exist or is inactive." }, { "id": "/api/partner-api-integration-flow", "title": "Build a partner ticketing flow", "path": "/api/partner-api-integration-flow", - "content": "This guide connects the Showpass event catalog, purchase widget, Partner API, and webhooks into one customer journey.\nYou need:\n- Partner API credentials provided by Showpass.\n- The Showpass organization ID whose events you want to display.\n- The Showpass JavaScript SDK installed in your frontend.\n- A public HTTPS endpoint that can receive Showpass webhooks.\nAll /api/partner/ requests belong in your backend. Event discovery and the purchase widget use their existing public integration paths.\nWhen a customer registers—or before their first Showpass checkout—send their stable ID and verified identity information to Showpass:\n``http\nPOST /api/partner/users/\n`\n`json\n{\n \"partner_user_id\": \"customer-42\",\n \"email\": \"buyer@example.com\",\n \"email_verified\": true,\n \"first_name\": \"Taylor\",\n \"last_name\": \"Buyer\"\n}\n`\nUse an immutable ID from your database for partner_user_id, not an email address. You will use the same ID to request checkout tokens and manage-order links. See Sync a customer with Showpass.\nQuery the Discovery API from your backend and render the results in your application:\n`http\nGET https://www.showpass.com/api/public/discovery/?venue=ORGANIZATION_ID\n`\nKeep the slug returned for each event. The purchase widget uses it to identify what the customer is buying.\nFor upcoming-only results, multiple organizations, recurring instances, pagination, and filters, see List events by organization.\nImmediately before opening checkout, ask your backend for a fresh token:\n`http\nPOST /api/partner/customer-attribution-token/\n`\n`json\n{\n \"partner_user_id\": \"customer-42\"\n}\n`\nReturn the customer_attribution_token to the frontend that is about to launch the widget. The token expires after one hour and should not be cached as a long-lived customer credential.\nPass the selected event slug and attribution token in the widget parameters:\n`javascript\nshowpass.tickets.eventPurchaseWidget(selectedEvent.slug, {\n \"customer_attribution_token\": customerAttributionToken\n});\n`\nTo embed che" + "content": "This guide connects the Showpass event catalog, purchase widget, Partner API, and webhooks into one customer journey.\nYou need:\n- Partner API credentials provided by Showpass.\n- The Showpass organization ID whose events you want to display.\n- The Showpass JavaScript SDK installed in your frontend.\n- A public HTTPS endpoint that can receive Showpass webhooks.\nAll /api/partner/ requests belong in your backend. Event discovery and the purchase widget use their existing public integration paths.\nWhen a customer registers—or before their first Showpass checkout—send their stable ID and verified identity information to Showpass:\n``http\nPOST /api/partner/users/\n`\n`json\n{\n \"partner_external_user_id\": \"customer-42\",\n \"email\": \"buyer@example.com\",\n \"email_verified\": true,\n \"first_name\": \"Taylor\",\n \"last_name\": \"Buyer\"\n}\n`\nUse an immutable ID from your database for partner_external_user_id, not an email address. You will use the same ID to request checkout tokens and manage-order links. See Sync a customer with Showpass.\nQuery the Discovery API from your backend and render the results in your application:\n`http\nGET https://www.showpass.com/api/public/discovery/?venue=ORGANIZATION_ID\n`\nKeep the slug returned for each event. The purchase widget uses it to identify what the customer is buying.\nFor upcoming-only results, multiple organizations, recurring instances, pagination, and filters, see List events by organization.\nImmediately before opening checkout, ask your backend for a fresh token:\n`http\nPOST /api/partner/customer-attribution-token/\n`\n`json\n{\n \"partner_external_user_id\": \"customer-42\"\n}\n`\nReturn the customer_attribution_token to the frontend that is about to launch the widget. The token expires after one hour and should not be cached as a long-lived customer credential.\nPass the selected event slug and attribution token in the widget parameters:\n`javascript\nshowpass.tickets.eventPurchaseWidget(selectedEvent.slug, {\n \"customer_attribution_token\": customerAttribut" }, { "id": "/api/partner-api-order-manage-link", "title": "Send a customer to their order", "path": "/api/partner-api-order-manage-link", - "content": "Create a short-lived link that opens a customer’s completed order in Showpass. Use it for View tickets, View receipt, or Manage order actions in your application.\n``http\nPOST /api/partner/orders/manage-link/\n`\nCall this endpoint from your backend only. Showpass verifies that the transaction belongs to the supplied Partner customer and is within the integration’s organization scope.\nAuthenticate the request with the HMAC scheme in the Partner API overview.\n`json\n{\n \"partner_user_id\": \"customer-42\",\n \"transaction_id\": \"showpass-transaction-id\"\n}\n`\nUse the same partner_user_id used for checkout attribution. Store the Showpass transaction_id from the purchase webhook with your order record.\nThe endpoint returns 201:\n`json\n{\n \"manage_url\": \"https://www.showpass.com/account/partner-login/opaque-code/\",\n \"expires_in_seconds\": 120\n}\n`\nNavigate the customer’s browser to manage_url as a top-level page. The link expires after 120 seconds and can be used once, so request it when the customer clicks the action rather than generating it in advance.\n1. Showpass consumes the one-time code.\n2. Showpass creates access scoped to the requested order—not a full Showpass account session.\n3. The customer is redirected to the standard Showpass order page.\n4. The final browser URL does not contain the one-time code.\nDo not embed manage_url in an iframe, store it as a permanent order URL, or send it to another customer.\nInvalid, expired, used, or out-of-scope links do not create access. A direct visit with an invalid code returns the customer to the Showpass login flow.\n- 400 Bad Request: a customer or transaction ID is missing or invalid.\n- 403 Forbidden: authentication failed or the order is outside the Partner integration’s organization scope.\n- 409 Conflict`: the customer or order cannot be found, the customer is inactive, or the order does not belong to that customer." + "content": "Create a short-lived link that opens a customer’s completed order in Showpass. Use it for View tickets, View receipt, or Manage order actions in your application.\n``http\nPOST /api/partner/orders/manage-link/\n`\nCall this endpoint from your backend only. Showpass verifies that the transaction belongs to the supplied Partner customer and is within the integration’s organization scope.\nAuthenticate the request with the HMAC scheme in the Partner API overview.\n`json\n{\n \"partner_external_user_id\": \"customer-42\",\n \"transaction_id\": \"showpass-transaction-id\"\n}\n`\nUse the same partner_external_user_id used for checkout attribution. Store the Showpass transaction_id from the purchase webhook with your order record.\nThe endpoint returns 201:\n`json\n{\n \"manage_url\": \"https://www.showpass.com/account/partner-login/opaque-code/\",\n \"expires_in_seconds\": 120\n}\n`\nNavigate the customer’s browser to manage_url as a top-level page. The link expires after 120 seconds and can be used once, so request it when the customer clicks the action rather than generating it in advance.\n1. Showpass consumes the one-time code.\n2. Showpass creates access scoped to the requested order—not a full Showpass account session.\n3. The customer is redirected to the standard Showpass order page.\n4. The final browser URL does not contain the one-time code.\nDo not embed manage_url in an iframe, store it as a permanent order URL, or send it to another customer.\nInvalid, expired, used, or out-of-scope links do not create access. A direct visit with an invalid code returns the customer to the Showpass login flow.\n- 400 Bad Request: a customer or transaction ID is missing or invalid.\n- 403 Forbidden: authentication failed or the order is outside the Partner integration’s organization scope.\n- 409 Conflict`: the customer or order cannot be found, the customer is inactive, or the order does not belong to that customer." }, { "id": "/api/partner-api-overview", "title": "Partner API overview", "path": "/api/partner-api-overview", - "content": "Use the Partner API when your application owns the customer experience and Showpass provides event discovery, checkout, tickets, and order management.\nThe Partner API connects a customer in your system to their Showpass purchase. It complements the Public Discovery API, the Ticket Purchase Widget, and Showpass webhooks.\n| Your application | Showpass |\n| --- | --- |\n| Owns the customer record and stable customer ID. | Links that ID to a Showpass customer. |\n| Displays events returned by the Discovery API. | Owns event inventory and availability. |\n| Opens the Showpass purchase widget. | Runs ticket selection, checkout, and payment. |\n| Receives and reconciles order webhooks. | Owns orders, tickets, refunds, and transfers. |\n| Requests an order-management link. | Gives the customer scoped access to the Showpass order page. |\n1. Your backend syncs the customer using the stable ID from your system as partner_user_id.\n2. Your application discovers Showpass events by organization and keeps the selected event slug.\n3. Immediately before checkout, your backend creates a customer attribution token.\n4. Your frontend passes the event slug and token to the Ticket Purchase Widget.\n5. Showpass validates the token and records the partner customer on the basket and completed order.\n6. Webhook payloads identify the partner customer, so your system can reconcile order activity.\n7. When the customer needs their tickets or receipt, your backend creates a manage-order link.\nSee Build a partner ticketing flow for the complete sequence and implementation examples.\npartner_user_id is your stable identifier for a customer. A customer_attribution_token carries that server-owned relationship into a Showpass checkout. The token provides purchase attribution only: it does not sign a customer in, prove their identity in the browser, or create a full Showpass session.\nPartner credentials authenticate your backend. Never send the partner secret, partner_user_id, bearer tokens, or refresh tokens to" + "content": "Use the Partner API when your application owns the customer experience and Showpass provides event discovery, checkout, tickets, and order management.\nThe Partner API connects a customer in your system to their Showpass purchase. It complements the Public Discovery API, the Ticket Purchase Widget, and Showpass webhooks.\n| Your application | Showpass |\n| --- | --- |\n| Owns the customer record and stable customer ID. | Links that ID to a Showpass customer. |\n| Displays events returned by the Discovery API. | Owns event inventory and availability. |\n| Opens the Showpass purchase widget. | Runs ticket selection, checkout, and payment. |\n| Receives and reconciles order webhooks. | Owns orders, tickets, refunds, and transfers. |\n| Requests an order-management link. | Gives the customer scoped access to the Showpass order page. |\n1. Your backend syncs the customer using the stable ID from your system as partner_external_user_id.\n2. Your application discovers Showpass events by organization and keeps the selected event slug.\n3. Immediately before checkout, your backend creates a customer attribution token.\n4. Your frontend passes the event slug and token to the Ticket Purchase Widget.\n5. Showpass validates the token and records the partner customer on the basket and completed order.\n6. Webhook payloads identify the partner customer, so your system can reconcile order activity.\n7. When the customer needs their tickets or receipt, your backend creates a manage-order link.\nSee Build a partner ticketing flow for the complete sequence and implementation examples.\npartner_external_user_id is your stable identifier for a customer. A customer_attribution_token carries that server-owned relationship into a Showpass checkout. The token provides purchase attribution only: it does not sign a customer in, prove their identity in the browser, or create a full Showpass session.\nPartner credentials authenticate your backend. Never send the partner secret, partner_external_user_id, bearer t" }, { "id": "/api/partner-api-users", "title": "Sync a customer with Showpass", "path": "/api/partner-api-users", - "content": "Connect a customer record in your application to Showpass. Do this when the customer registers or before their first attributed checkout.\n``http\nPOST /api/partner/users/\n`\nThis is an idempotent server-to-server operation for a partner_user_id that already exists: Showpass reuses the existing customer link instead of creating another one.\nThe profile fields are used when Showpass creates or safely links the customer. Repeating the request for an existing partner_user_id confirms and returns the current link; it does not update that customer’s Showpass profile.\nAuthenticate the request with the HMAC scheme in the Partner API overview.\npartner_user_id is the durable connection between your customer and their Showpass activity. Use an immutable database ID from your system. Do not use an email address or another value that can change.\nThe same ID is returned in attributed webhooks and is required when creating a fresh checkout token or manage-order link.\n`json\n{\n \"partner_user_id\": \"customer-42\",\n \"email\": \"buyer@example.com\",\n \"email_verified\": true,\n \"first_name\": \"Taylor\",\n \"last_name\": \"Buyer\",\n \"phone\": null\n}\n`\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| partner_user_id | string | Yes | Stable customer ID from your system, up to 255 characters. It is trimmed and lowercased. |\n| email | string | Yes | Customer email address, up to 128 characters. |\n| email_verified | boolean | Yes | Whether your application has verified the email. When true, Showpass may safely link an existing Showpass customer with the same email. |\n| first_name | string | No | First name, up to 32 characters. |\n| last_name | string or null | No | Last name, up to 32 characters. |\n| phone | string or null | No | Phone number, up to 32 characters. |\n| venue_id | integer or null | No | Showpass organization scope for this request. It must match the scope configured for the Partner integration. |\nThe endpoint returns 201 when it creates a customer link and 200 when it" + "content": "Connect a customer record in your application to Showpass. Do this when the customer registers or before their first attributed checkout.\n``http\nPOST /api/partner/users/\n`\nThis is an idempotent server-to-server operation for a partner_external_user_id that already exists: Showpass reuses the existing customer link instead of creating another one.\nThe profile fields are used when Showpass creates or safely links the customer. Repeating the request for an existing partner_external_user_id confirms and returns the current link; it does not update that customer’s Showpass profile.\nAuthenticate the request with the HMAC scheme in the Partner API overview.\npartner_external_user_id is the durable connection between your customer and their Showpass activity. Use an immutable database ID from your system. Do not use an email address or another value that can change.\nThe same ID is returned in attributed webhooks and is required when creating a fresh checkout token or manage-order link.\n`json\n{\n \"partner_external_user_id\": \"customer-42\",\n \"email\": \"buyer@example.com\",\n \"email_verified\": true,\n \"first_name\": \"Taylor\",\n \"last_name\": \"Buyer\",\n \"phone\": null\n}\n`\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| partner_external_user_id | string | Yes | Stable customer ID from your system, up to 255 characters. It is trimmed and lowercased. |\n| email | string | Yes | Customer email address, up to 128 characters. |\n| email_verified | boolean | Yes | Whether your application has verified the email. When true, Showpass may safely link an existing Showpass customer with the same email. |\n| first_name | string | No | First name, up to 32 characters. |\n| last_name | string or null | No | Last name, up to 32 characters. |\n| phone | string or null | No | Phone number, up to 32 characters. |\n| venue_id | integer or null | No | Showpass organization scope for this request. It must match the scope configured for the Partner integration. |\nThe endpoint returns 201 wh" }, { "id": "/api/partner-api-webhooks", "title": "Match orders to your customers", "path": "/api/partner-api-webhooks", - "content": "Showpass webhooks report purchases and post-purchase changes. For an attributed checkout, the payload can include the stable customer ID from your system:\n``json\n{\n \"event_type\": \"invoice.purchase\",\n \"data\": {\n \"partner_slug\": \"your-partner\",\n \"partner_user_id\": \"customer-42\"\n }\n}\n`\nUse partner_user_id to find the customer in your system. Use the webhook’s Showpass transaction identifier to find or create the corresponding order record.\nThe Partner fields extend the existing event-specific data object. They do not replace the normal invoice, customer, ticket, or transaction fields documented for that webhook.\nPartner attribution can be included on these existing events:\n| Event | Use it to |\n| --- | --- |\n| invoice.purchase | Record a completed purchase. |\n| invoice.refund | Reconcile a refund. |\n| invoice.void | Mark a transaction as voided. |\n| invoice.transfer | Record the recipient-side order and tickets created by a transfer. |\n| invoice.transferred | Update the original purchaser’s order and tickets after a transfer. |\nChoose the events required by your product. Most integrations begin with invoice.purchase and add refund, void, and transfer events when they display post-purchase order state.\nPartner attribution does not create a separate webhook or receiver. Configure the normal Showpass webhook events and URL, then verify every delivery using the documented X-SHOWPASS-SIGNATURE header before processing it.\nSee Webhook setup and management, webhook security, and the invoice payload reference.\nProcess deliveries idempotently using the webhook event identifier or the equivalent event-specific identifier. Expect retries and events that arrive after the initial purchase.\nShowpass includes Partner fields only when it can resolve one clear Partner customer for the order. If no attribution exists—or the match is ambiguous—the normal webhook is still delivered without partner_slug and partner_user_id`.\nTreat missing Partner fields as an unattributed Showpass" + "content": "Showpass webhooks report purchases and post-purchase changes. For an attributed checkout, the payload can include the stable customer ID from your system:\n``json\n{\n \"event_type\": \"invoice.purchase\",\n \"data\": {\n \"partner_slug\": \"your-partner\",\n \"partner_external_user_id\": \"customer-42\"\n }\n}\n`\nUse partner_external_user_id to find the customer in your system. Use the webhook’s Showpass transaction identifier to find or create the corresponding order record.\nThe Partner fields extend the existing event-specific data object. They do not replace the normal invoice, customer, ticket, or transaction fields documented for that webhook.\nPartner attribution can be included on these existing events:\n| Event | Use it to |\n| --- | --- |\n| invoice.purchase | Record a completed purchase. |\n| invoice.refund | Reconcile a refund. |\n| invoice.void | Mark a transaction as voided. |\n| invoice.transfer | Record the recipient-side order and tickets created by a transfer. |\n| invoice.transferred | Update the original purchaser’s order and tickets after a transfer. |\nChoose the events required by your product. Most integrations begin with invoice.purchase and add refund, void, and transfer events when they display post-purchase order state.\nPartner attribution does not create a separate webhook or receiver. Configure the normal Showpass webhook events and URL, then verify every delivery using the documented X-SHOWPASS-SIGNATURE header before processing it.\nSee Webhook setup and management, webhook security, and the invoice payload reference.\nProcess deliveries idempotently using the webhook event identifier or the equivalent event-specific identifier. Expect retries and events that arrive after the initial purchase.\nShowpass includes Partner fields only when it can resolve one clear Partner customer for the order. If no attribution exists—or the match is ambiguous—the normal webhook is still delivered without partner_slug and partner_external_user_id`.\nTreat missing Partner fields " }, { "id": "/cli/overview", @@ -273,7 +273,7 @@ "id": "/webhooks/webhooks-introduction", "title": "Showpass Webhooks: Introduction", "path": "/webhooks/webhooks-introduction", - "content": "Showpass webhooks enable real-time notifications when events occur in your account, allowing you to automate workflows and integrate with external systems.\nWebhooks are HTTP callbacks that Showpass sends to your server when specific events happen. Like a new purchase, refund, or ticket transfer. Your application receives instant notifications and can respond automatically.\n---\nA publicly accessible URL on your server (or on a third-party service such as Zapier) where Showpass can send HTTP POST requests containing event data. You will listen for Showpass events at this endpoint.\nExample: https://yoursite.com/api/showpass-webhook\n---\nEvent is an action within Showpass that triggers a webhook notification. You can find the list of events in section 4.\n---\nJSON data sent from Showpass containing event details. For invoice events, this includes the complete invoice object with customer info, items purchased, and transaction details.\n---\nA unique token provided when you create an endpoint. Use this to verify webhook authenticity by validating the X-SHOWPASS-SIGNATURE header.\n> Security: Always verify signatures to ensure requests genuinely come from Showpass.\n---\nShowpass maintains delivery logs showing success/failure status for each webhook attempt. Use these for monitoring and troubleshooting.\n---\nSupported Partner integrations can optionally receive partner_slug and\npartner_user_id in webhook payloads. This uses the existing webhook events and\nURL.\nSee Partner attribution in webhooks for details.\n---\nGet immediate notifications as events happen—no polling or manual checks required.\nConnect Showpass with CRM systems, email platforms, accounting software, analytics tools, and custom applications.\nAutomate tasks like:\n- Updating customer records in your CRM\n- Sending custom receipts or confirmation emails\n- Syncing sales data with accounting software\n- Managing mailing lists based on purchases\n- Triggering inventory updates\nEliminate manual data entry and frequent API p" + "content": "Showpass webhooks enable real-time notifications when events occur in your account, allowing you to automate workflows and integrate with external systems.\nWebhooks are HTTP callbacks that Showpass sends to your server when specific events happen. Like a new purchase, refund, or ticket transfer. Your application receives instant notifications and can respond automatically.\n---\nA publicly accessible URL on your server (or on a third-party service such as Zapier) where Showpass can send HTTP POST requests containing event data. You will listen for Showpass events at this endpoint.\nExample: https://yoursite.com/api/showpass-webhook\n---\nEvent is an action within Showpass that triggers a webhook notification. You can find the list of events in section 4.\n---\nJSON data sent from Showpass containing event details. For invoice events, this includes the complete invoice object with customer info, items purchased, and transaction details.\n---\nA unique token provided when you create an endpoint. Use this to verify webhook authenticity by validating the X-SHOWPASS-SIGNATURE header.\n> Security: Always verify signatures to ensure requests genuinely come from Showpass.\n---\nShowpass maintains delivery logs showing success/failure status for each webhook attempt. Use these for monitoring and troubleshooting.\n---\nSupported Partner integrations can optionally receive partner_slug and\npartner_external_user_id in webhook payloads. This uses the existing webhook events and\nURL.\nSee Partner attribution in webhooks for details.\n---\nGet immediate notifications as events happen—no polling or manual checks required.\nConnect Showpass with CRM systems, email platforms, accounting software, analytics tools, and custom applications.\nAutomate tasks like:\n- Updating customer records in your CRM\n- Sending custom receipts or confirmation emails\n- Syncing sales data with accounting software\n- Managing mailing lists based on purchases\n- Triggering inventory updates\nEliminate manual data entry and frequ" }, { "id": "/webhooks/webhooks-setup-and-management", diff --git a/src/docs-app/data/api/partner-api-customer-attribution-token.md b/src/docs-app/data/api/partner-api-customer-attribution-token.md index 7791b6b..6c5fe4f 100644 --- a/src/docs-app/data/api/partner-api-customer-attribution-token.md +++ b/src/docs-app/data/api/partner-api-customer-attribution-token.md @@ -14,7 +14,7 @@ Authenticate the request with the HMAC scheme in the [Partner API overview](/api ```json { - "partner_user_id": "customer-42" + "partner_external_user_id": "customer-42" } ``` @@ -51,6 +51,6 @@ The raw value is returned only in this response; Showpass stores its SHA-256 has ## Errors -- `400 Bad Request`: `partner_user_id` is missing or invalid. +- `400 Bad Request`: `partner_external_user_id` is missing or invalid. - `403 Forbidden`: authentication failed or checkout attribution is not enabled for this Partner integration. - `409 Conflict`: the Partner customer does not exist or is inactive. diff --git a/src/docs-app/data/api/partner-api-integration-flow.md b/src/docs-app/data/api/partner-api-integration-flow.md index 6843717..9697071 100644 --- a/src/docs-app/data/api/partner-api-integration-flow.md +++ b/src/docs-app/data/api/partner-api-integration-flow.md @@ -23,7 +23,7 @@ POST /api/partner/users/ ```json { - "partner_user_id": "customer-42", + "partner_external_user_id": "customer-42", "email": "buyer@example.com", "email_verified": true, "first_name": "Taylor", @@ -31,7 +31,7 @@ POST /api/partner/users/ } ``` -Use an immutable ID from your database for `partner_user_id`, not an email address. You will use the same ID to request checkout tokens and manage-order links. See [Sync a customer with Showpass](/api/partner-api-users). +Use an immutable ID from your database for `partner_external_user_id`, not an email address. You will use the same ID to request checkout tokens and manage-order links. See [Sync a customer with Showpass](/api/partner-api-users). ## 2. Display the organization’s events @@ -55,7 +55,7 @@ POST /api/partner/customer-attribution-token/ ```json { - "partner_user_id": "customer-42" + "partner_external_user_id": "customer-42" } ``` @@ -75,7 +75,7 @@ To embed checkout in a page instead of opening a modal, pass a container ID as t Showpass validates the token server-side and records the partner customer on the checkout basket and resulting order. The customer still enters their buyer details through normal Showpass checkout. -The widget does not need or accept the Partner API secret, `partner_user_id`, a Showpass bearer token, or a checkout handoff code. +The widget does not need or accept the Partner API secret, `partner_external_user_id`, a Showpass bearer token, or a checkout handoff code. ## 5. Reconcile order activity @@ -86,12 +86,12 @@ Subscribe to the invoice events your application needs. When an order has one cl "event_type": "invoice.purchase", "data": { "partner_slug": "your-partner", - "partner_user_id": "customer-42" + "partner_external_user_id": "customer-42" } } ``` -Use `partner_user_id` to locate the customer and the webhook’s Showpass transaction identifier to update the correct order. Always verify `X-SHOWPASS-SIGNATURE` before processing a delivery. See [Match orders to your customers](/api/partner-api-webhooks). +Use `partner_external_user_id` to locate the customer and the webhook’s Showpass transaction identifier to update the correct order. Always verify `X-SHOWPASS-SIGNATURE` before processing a delivery. See [Match orders to your customers](/api/partner-api-webhooks). ## 6. Let the customer manage an order @@ -103,7 +103,7 @@ POST /api/partner/orders/manage-link/ ```json { - "partner_user_id": "customer-42", + "partner_external_user_id": "customer-42", "transaction_id": "showpass-transaction-id" } ``` diff --git a/src/docs-app/data/api/partner-api-order-manage-link.md b/src/docs-app/data/api/partner-api-order-manage-link.md index b517756..fd33819 100644 --- a/src/docs-app/data/api/partner-api-order-manage-link.md +++ b/src/docs-app/data/api/partner-api-order-manage-link.md @@ -14,12 +14,12 @@ Authenticate the request with the HMAC scheme in the [Partner API overview](/api ```json { - "partner_user_id": "customer-42", + "partner_external_user_id": "customer-42", "transaction_id": "showpass-transaction-id" } ``` -Use the same `partner_user_id` used for checkout attribution. Store the Showpass `transaction_id` from the purchase webhook with your order record. +Use the same `partner_external_user_id` used for checkout attribution. Store the Showpass `transaction_id` from the purchase webhook with your order record. ## Response diff --git a/src/docs-app/data/api/partner-api-overview.md b/src/docs-app/data/api/partner-api-overview.md index 08714d6..8c697c8 100644 --- a/src/docs-app/data/api/partner-api-overview.md +++ b/src/docs-app/data/api/partner-api-overview.md @@ -16,7 +16,7 @@ The Partner API connects a customer in your system to their Showpass purchase. I ## How a purchase is connected -1. Your backend [syncs the customer](/api/partner-api-users) using the stable ID from your system as `partner_user_id`. +1. Your backend [syncs the customer](/api/partner-api-users) using the stable ID from your system as `partner_external_user_id`. 2. Your application [discovers Showpass events by organization](/api/public-api-event-list-by-organization) and keeps the selected event `slug`. 3. Immediately before checkout, your backend [creates a customer attribution token](/api/partner-api-customer-attribution-token). 4. Your frontend passes the event slug and token to the [Ticket Purchase Widget](/sdk/ticket-purchase-widget). @@ -28,9 +28,9 @@ See [Build a partner ticketing flow](/api/partner-api-integration-flow) for the ## Identity and authentication are separate -`partner_user_id` is your stable identifier for a customer. A `customer_attribution_token` carries that server-owned relationship into a Showpass checkout. The token provides purchase attribution only: it does not sign a customer in, prove their identity in the browser, or create a full Showpass session. +`partner_external_user_id` is your stable identifier for a customer. A `customer_attribution_token` carries that server-owned relationship into a Showpass checkout. The token provides purchase attribution only: it does not sign a customer in, prove their identity in the browser, or create a full Showpass session. -Partner credentials authenticate your backend. Never send the partner secret, `partner_user_id`, bearer tokens, or refresh tokens to the purchase widget. +Partner credentials authenticate your backend. Never send the partner secret, `partner_external_user_id`, bearer tokens, or refresh tokens to the purchase widget. ## Base URL and access @@ -71,7 +71,7 @@ import time import uuid partner_secret = "your-partner-secret" -body = '{"partner_user_id":"customer-42"}' +body = '{"partner_external_user_id":"customer-42"}' timestamp = str(int(time.time())) nonce = str(uuid.uuid4()) path_and_query = "/api/partner/customer-attribution-token/" diff --git a/src/docs-app/data/api/partner-api-users.md b/src/docs-app/data/api/partner-api-users.md index d25a3a3..535281c 100644 --- a/src/docs-app/data/api/partner-api-users.md +++ b/src/docs-app/data/api/partner-api-users.md @@ -6,15 +6,15 @@ Connect a customer record in your application to Showpass. Do this when the cust POST /api/partner/users/ ``` -This is an idempotent server-to-server operation for a `partner_user_id` that already exists: Showpass reuses the existing customer link instead of creating another one. +This is an idempotent server-to-server operation for a `partner_external_user_id` that already exists: Showpass reuses the existing customer link instead of creating another one. -The profile fields are used when Showpass creates or safely links the customer. Repeating the request for an existing `partner_user_id` confirms and returns the current link; it does not update that customer’s Showpass profile. +The profile fields are used when Showpass creates or safely links the customer. Repeating the request for an existing `partner_external_user_id` confirms and returns the current link; it does not update that customer’s Showpass profile. Authenticate the request with the HMAC scheme in the [Partner API overview](/api/partner-api-overview). ## Choose the customer ID -`partner_user_id` is the durable connection between your customer and their Showpass activity. Use an immutable database ID from your system. Do not use an email address or another value that can change. +`partner_external_user_id` is the durable connection between your customer and their Showpass activity. Use an immutable database ID from your system. Do not use an email address or another value that can change. The same ID is returned in attributed webhooks and is required when creating a fresh checkout token or manage-order link. @@ -22,7 +22,7 @@ The same ID is returned in attributed webhooks and is required when creating a f ```json { - "partner_user_id": "customer-42", + "partner_external_user_id": "customer-42", "email": "buyer@example.com", "email_verified": true, "first_name": "Taylor", @@ -33,7 +33,7 @@ The same ID is returned in attributed webhooks and is required when creating a f | Field | Type | Required | Description | | --- | --- | --- | --- | -| `partner_user_id` | string | Yes | Stable customer ID from your system, up to 255 characters. It is trimmed and lowercased. | +| `partner_external_user_id` | string | Yes | Stable customer ID from your system, up to 255 characters. It is trimmed and lowercased. | | `email` | string | Yes | Customer email address, up to 128 characters. | | `email_verified` | boolean | Yes | Whether your application has verified the email. When `true`, Showpass may safely link an existing Showpass customer with the same email. | | `first_name` | string | No | First name, up to 32 characters. | @@ -48,7 +48,7 @@ The endpoint returns `201` when it creates a customer link and `200` when it reu ```json { "partner_identity_id": 123, - "partner_user_id": "customer-42", + "partner_external_user_id": "customer-42", "status": "active", "link_reason": "created_user", "venue_id": 456, @@ -62,7 +62,7 @@ The token fields are included only when checkout attribution is enabled for the `link_reason` explains how Showpass resolved the customer: - `created_user`: Showpass created a customer and partner link. -- `reused_existing`: this `partner_user_id` was already linked. +- `reused_existing`: this `partner_external_user_id` was already linked. - `email_auto_linked`: the verified email was safely linked to an existing Showpass customer. Showpass returns a conflict instead of silently linking customers when the email, identity status, or organization scope is unsafe or ambiguous. diff --git a/src/docs-app/data/api/partner-api-webhooks.md b/src/docs-app/data/api/partner-api-webhooks.md index 09799a3..840a93d 100644 --- a/src/docs-app/data/api/partner-api-webhooks.md +++ b/src/docs-app/data/api/partner-api-webhooks.md @@ -7,12 +7,12 @@ Showpass webhooks report purchases and post-purchase changes. For an attributed "event_type": "invoice.purchase", "data": { "partner_slug": "your-partner", - "partner_user_id": "customer-42" + "partner_external_user_id": "customer-42" } } ``` -Use `partner_user_id` to find the customer in your system. Use the webhook’s Showpass transaction identifier to find or create the corresponding order record. +Use `partner_external_user_id` to find the customer in your system. Use the webhook’s Showpass transaction identifier to find or create the corresponding order record. The Partner fields extend the existing event-specific `data` object. They do not replace the normal invoice, customer, ticket, or transaction fields documented for that webhook. @@ -40,6 +40,6 @@ Process deliveries idempotently using the webhook event identifier or the equiva ## When Partner fields are absent -Showpass includes Partner fields only when it can resolve one clear Partner customer for the order. If no attribution exists—or the match is ambiguous—the normal webhook is still delivered without `partner_slug` and `partner_user_id`. +Showpass includes Partner fields only when it can resolve one clear Partner customer for the order. If no attribution exists—or the match is ambiguous—the normal webhook is still delivered without `partner_slug` and `partner_external_user_id`. Treat missing Partner fields as an unattributed Showpass order. Do not infer the Partner customer from buyer email alone. diff --git a/src/docs-app/data/partnerApiExamplesMap.ts b/src/docs-app/data/partnerApiExamplesMap.ts index ed75e08..bf019c4 100644 --- a/src/docs-app/data/partnerApiExamplesMap.ts +++ b/src/docs-app/data/partnerApiExamplesMap.ts @@ -11,13 +11,13 @@ const partnerApiExamplesMap: Record = { description: `Connect a customer in your system to Showpass. ${partnerHmacSigningNote}`, examples: partnerHmacExamples( "/api/partner/users/", - '{"partner_user_id":"customer-42","email":"customer@example.com","email_verified":true}', + '{"partner_external_user_id":"customer-42","email":"customer@example.com","email_verified":true}', ), response: { status: 201, body: { partner_identity_id: 123, - partner_user_id: "customer-42", + partner_external_user_id: "customer-42", status: "active", link_reason: "created_user", venue_id: 456, @@ -30,7 +30,7 @@ const partnerApiExamplesMap: Record = { description: "Create checkout attribution for a connected customer", examples: partnerHmacExamples( "/api/partner/customer-attribution-token/", - '{"partner_user_id":"customer-42"}', + '{"partner_external_user_id":"customer-42"}', ), response: { status: 201, @@ -46,7 +46,7 @@ const partnerApiExamplesMap: Record = { description: "Send a customer to their completed Showpass order", examples: partnerHmacExamples( "/api/partner/orders/manage-link/", - '{"partner_user_id":"customer-42","transaction_id":"transaction-id"}', + '{"partner_external_user_id":"customer-42","transaction_id":"transaction-id"}', ), response: { status: 201, diff --git a/src/docs-app/data/seoData.ts b/src/docs-app/data/seoData.ts index 470c092..8cc6a7d 100644 --- a/src/docs-app/data/seoData.ts +++ b/src/docs-app/data/seoData.ts @@ -57,7 +57,7 @@ export const seoDataMap: Record = { "/api/partner-api-users": { title: "Sync a Customer - Showpass Partner API", description: "Connect a customer in your application to Showpass using a stable partner customer ID.", - keywords: "showpass partner customer api, customer identity sync, partner user id, hmac api authentication" + keywords: "showpass partner customer api, customer identity sync, partner external user id, hmac api authentication" }, "/api/partner-api-customer-attribution-token": { title: "Create Checkout Attribution - Showpass Partner API", diff --git a/src/docs-app/data/webhooks/01-webhooks-introduction.md b/src/docs-app/data/webhooks/01-webhooks-introduction.md index 562f791..720ce50 100644 --- a/src/docs-app/data/webhooks/01-webhooks-introduction.md +++ b/src/docs-app/data/webhooks/01-webhooks-introduction.md @@ -47,7 +47,7 @@ Showpass maintains delivery logs showing success/failure status for each webhook ## Partner attribution Supported Partner integrations can optionally receive `partner_slug` and -`partner_user_id` in webhook payloads. This uses the existing webhook events and +`partner_external_user_id` in webhook payloads. This uses the existing webhook events and URL. See [Partner attribution in webhooks](/api/partner-api-webhooks) for details.