> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/api-v1/v1-customers.md).

# v1-customers

Customer management (v1)

## List customers (v1)

> List customers with filtering and pagination.\
> \
> Additional filter query parameters are available depending on the resource.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"v1-customers","description":"Customer management (v1)"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["customers"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"V1ListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true},"description":"Array of resource objects"},"page":{"type":"integer","description":"Current page number"},"per_page":{"type":"integer","description":"Items per page"},"total":{"type":"integer","description":"Total number of items"},"total_pages":{"type":"integer","description":"Total number of pages"}},"required":["data","page","per_page","total","total_pages"]},"V1ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}},"paths":{"/v1/customers":{"get":{"tags":["v1-customers"],"summary":"List customers (v1)","description":"List customers with filtering and pagination.\n\nAdditional filter query parameters are available depending on the resource.","parameters":[{"schema":{"type":"integer","description":"Page number (1-based)"},"required":false,"description":"Page number (1-based)","name":"page","in":"query"},{"schema":{"type":"integer","description":"Items per page (default 50)"},"required":false,"description":"Items per page (default 50)","name":"per_page","in":"query"},{"schema":{"type":"string","description":"Sort field (prefix with - for descending)"},"required":false,"description":"Sort field (prefix with - for descending)","name":"sort","in":"query"},{"schema":{"type":"string","description":"Full-text search query"},"required":false,"description":"Full-text search query","name":"search","in":"query"}],"responses":{"200":{"description":"Paginated list of resources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"403":{"description":"Forbidden / insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}}}}}}
```

## Send customer magic link email

> Sends a magic link email to the specified customer.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"v1-customers","description":"Customer management (v1)"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["customers"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"V1ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}},"paths":{"/v1/customers/{customer_id}/auth":{"post":{"tags":["v1-customers"],"summary":"Send customer magic link email","description":"Sends a magic link email to the specified customer.","parameters":[{"schema":{"type":"string","description":"Customer ID"},"required":true,"description":"Customer ID","name":"customer_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Redirect URL included in the magic link"}}}}}},"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"403":{"description":"Forbidden / insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}}}}}}
```

## Send magic link email by email address

> Sends a magic link email to a customer identified by email address.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"v1-customers","description":"Customer management (v1)"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["customers"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"V1ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}},"paths":{"/v1/customers/auth":{"post":{"tags":["v1-customers"],"summary":"Send magic link email by email address","description":"Sends a magic link email to a customer identified by email address.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Customer email address"},"url":{"type":"string","description":"Redirect URL included in the magic link"}},"required":["email"]}}}},"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"403":{"description":"Forbidden / insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}}}}}}
```

## Generate customer magic link token

> Generates a magic link token for the specified customer (does not send email).

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"v1-customers","description":"Customer management (v1)"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["customers"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"V1ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}},"paths":{"/v1/customers/{customer_id}/login":{"post":{"tags":["v1-customers"],"summary":"Generate customer magic link token","description":"Generates a magic link token for the specified customer (does not send email).","parameters":[{"schema":{"type":"string","description":"Customer ID"},"required":true,"description":"Customer ID","name":"customer_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Redirect URL included in the magic link"}}}}}},"responses":{"200":{"description":"Magic link token","content":{"application/json":{"schema":{"type":"object","properties":{"magic_link_token":{"type":"string"}},"required":["magic_link_token"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"403":{"description":"Forbidden / insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}}}}}}
```

## Generate magic link token by email

> Generates a magic link token for a customer identified by email address.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"v1-customers","description":"Customer management (v1)"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["customers"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"V1ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}},"paths":{"/v1/customers/login":{"post":{"tags":["v1-customers"],"summary":"Generate magic link token by email","description":"Generates a magic link token for a customer identified by email address.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Customer email address"},"url":{"type":"string","description":"Redirect URL included in the magic link"}},"required":["email"]}}}},"responses":{"200":{"description":"Magic link token","content":{"application/json":{"schema":{"type":"object","properties":{"magic_link_token":{"type":"string"}},"required":["magic_link_token"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"403":{"description":"Forbidden / insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorResponse"}}}}}}}}}
```
