API: Managing Customers

The Storefront API lets you create and manage customer accounts programmatically without needing to log in to Storefront Manager. This is useful if you have your own platform or control panel and want to automate customer provisioning when users sign up, sync customer records, or build tooling for your support team.

Note: DNS management via the API only works for domains using Storefront's default Shopco nameservers (a.ns.shopco.com, b.ns.shopco.com, c.ns.shopco.com). Domains using custom nameservers manage their own DNS outside of Storefront.

Before you begin

Requirements

• An active OpenSRS Storefront with API access enabled
• API credentials (Client ID and Client Secret) generated in Storefront Manager
• Your OpenSRS account balance above $10 to keep your Storefront active

Customer endpoints

Create a customer

Creates a new customer account under your reseller.

POST /v1/customer

Request fields

Notes:

• postal_code is validated against country at the database level.
• phone validation is country-aware.

Example request

{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "username": "janedoe01",
  "address1": "123 Main St",
  "city": "Toronto",
  "state": "Ontario",
  "postal_code": "M5V 2T6",
  "country": "CA",
  "phone": "+1 416 555 0101",
  "send_email": false,
  "currency_code": "CAD",
  "external_user_id": "cust-12345"
}

Example cURL

curl -X POST "https://api.shopco.com/v1/customer" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "username": "janedoe01",
    "address1": "123 Main St",
    "city": "Toronto",
    "state": "Ontario",
    "postal_code": "M5V 2T6",
    "country": "CA",
    "phone": "+1 416 555 0101",
    "send_email": false,
    "currency_code": "CAD",
    "external_user_id": "cust-12345"
  }'

Success response

200 OK — the new customer's UUID, returned as a JSON string.

"8d9f0ef8-6045-4bb2-b473-f7f5c2dcf0a8"

Get a customer

Returns a single customer by ID.

GET /v1/customer/{customer_id}

Path parameters

Example cURL

curl -X GET "https://api.shopco.com/v1/customer/8d9f0ef8-6045-4bb2-b473-f7f5c2dcf0a8" \
  -H "Authorization: Bearer <access_token>"

Success response

200 OK — a customer object.

Example response

{
  "id": "8d9f0ef8-6045-4bb2-b473-f7f5c2dcf0a8",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "username": "janedoe01",
  "status": "active",
  "created_date": "2026-04-01T10:00:00.000000Z",
  "last_login_date": null,
  "phone": "+1.4165550101",
  "address1": "123 Main St",
  "address2": null,
  "address3": null,
  "city": "Toronto",
  "state": "Ontario",
  "postal_code": "M5V 2T6",
  "country": "CA",
  "currency": {
    "code": "CAD",
    "symbol": "$",
    "descr": "Canadian Dollar"
  },
  "totp_enabled": false,
  "external_user_id": "cust-12345",
  "stripe_customer_id": null
}

Update a customer

Partially updates a customer. Only include the fields you want to change — omitted fields are left unchanged.

PATCH /v1/customer/{customer_id}

Path parameters

Request fields

All fields are optional. At least one must be provided.

Example request

{
  "city": "Vancouver",
  "state": "British Columbia",
  "external_user_id": "cust-12345-updated"
}

Example cURL

curl -X PATCH "https://api.shopco.com/v1/customer/8d9f0ef8-6045-4bb2-b473-f7f5c2dcf0a8" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Vancouver",
    "state": "British Columbia",
    "external_user_id": "cust-12345-updated"
  }'

Success response

200 OK — empty body.

Customer endpoints

Generate a customer SSO login URL

Generates a short-lived, single-use URL that logs a specific customer into Storefront without requiring their username and password. Use this to redirect a customer who's already authenticated on your own platform directly into their Storefront account — for example, from a "Manage Domains" button in your own portal.

POST /v1/customer/{customer_id}/sso_url

Path parameters

The request is rejected if the customer doesn't belong to your reseller account, or if your API credentials are invalid or missing.

Note: Use api.test.shopco.com against your test environment and api.shopco.com against your live environment.

Example cURL

curl -X POST \
"https://api.shopco.com/v1/customer/{customer_id}/sso_url" \
    -H "Authorization: Bearer <access_token>"

Success response

200 OK — a ready-to-use login URL and its expiry time.

{
  "url": "https://{your-storefront-domain}/login?token={token}",
  "expires_at": "2024-01-15T23:03:00Z"
}

Note: The url domain reflects your Storefront's configured domain — either your default Shopco subdomain or your own custom domain, if you've set one up.

Redirect the customer's browser to the returned url. No further request is needed — the URL already contains everything required to establish the session.

Behavior:

• Valid, unexpired, unused URL — the customer is logged in and redirected into their account.
• Invalid, expired, or already-used URL — the customer is redirected to the standard login page with an error message.
• The URL is invalidated the moment it's used, whether or not the login succeeds.

Note: The URL expires 15 minutes after it's generated and can only be used once. Generation is rate-limited per reseller. Token login bypasses any multi-factor authentication configured on the customer's account.

Error responses

Event logging

Every customer login completed through the API is recorded in your Storefront event log, so you can track how often it's used.

Error responses

All error responses follow this structure:

{ "detail": "<message>" }

For field validation errors (Pydantic):

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "first_name"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

HTTP status codes

Related articles

• API DNS Management Guide — Manage DNS records for your customers' domains

Questions or issues with the API? Contact OpenSRS Support.