> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Register Customer by Invoice Token

# Register Customer by Invoice Token

Creates a customer record and grants portal access using a `basketSession` GUID token paired with an invoice ID. This endpoint is called at the end of a guest checkout flow — after payment has been completed — to convert the guest into a registered customer. The combination of the invoice ID and the basket session token is used to verify the purchase, create (or link) the customer account, and return a new token that can be used for subsequent token-gated operations on that invoice.

## Authentication

No bearer token is required. Authentication is performed via the `token` query parameter, which must be the `basketSession` GUID associated with the completed guest checkout session.

## Path Parameters

<ParamField path="invoiceId" type="number" required>
  The unique identifier of the invoice generated during guest checkout. This is used alongside the basket session token to locate and validate the
  purchase.
</ParamField>

## Query Parameters

<ParamField query="token" type="string" required>
  The `basketSession` GUID token associated with the guest checkout session. This token is typically passed through the checkout completion URL and
  ties the anonymous session to the invoice, enabling customer record creation and portal access to be granted.
</ParamField>

## Response

<ResponseField name="Token" type="string">
  A new invoice-scoped token returned after successful customer registration. This token can be used for subsequent token-gated requests on this
  invoice, such as downloading the invoice PDF via `pdfByToken`.
</ResponseField>

## Example Response

```json theme={null}
{
  "Token": "eyJhbGciOiJIUzI1NiIsInR..."
}
```

## Usage in Portal

This endpoint is called on the guest checkout completion page immediately after a successful payment. It uses the `basketSession` GUID (available from the checkout URL or session state) together with the invoice ID to:

1. Verify the completed guest purchase.
2. Create a new customer record (or link to an existing one).
3. Grant the customer portal access.
4. Return a fresh token for follow-up token-gated operations (e.g. PDF download).

* File: `src/views/public/checkout/complete/index.tsx`

### Typical integration pattern

```ts theme={null}
// From src/api/endpoints.ts
// endpoints.billing.invoices.registerByToken = (invoiceId: number, basketSessionToken: string) => ({
//   url: `/api/public/billing/invoices/${invoiceId}/registerByToken?token=${basketSessionToken}`,
//   type: null as unknown as { Token: string },
// })

// Usage – called after guest checkout payment success
const endpoint = endpoints.billing.invoices.registerByToken(invoice.Id, basketSessionToken)
const result = await httpClient.post<{ Token: string }>(endpoint.url, {})
const invoiceToken = result.data.Token // use for pdfByToken or other token-gated requests
```

## Related Endpoints

* `GET /api/public/billing/invoices/{invoiceId}/pdfByToken` – Download invoice PDF using a guest token
* `GET /api/public/billing/invoices/{invoiceId}` – Get full invoice details (authenticated)

## Error Responses

<ResponseField name="401 Unauthorized" type="error">
  The provided `basketSession` token is invalid, has already been used, or has expired.
</ResponseField>

<ResponseField name="404 Not Found" type="error">
  No invoice exists with the specified ID, or the token does not match the invoice.
</ResponseField>