Customer portal API reference

Conventions

• CORS: You must specify the domains your portal will run on (see Enable the customer portal). This blocks certain attacks and unauthorized access, and does prevent use in very old browsers.

• REST: GET retrieves data and should have no body. POST creates something new. PATCH modifies an existing thing.

• Request bodies: For POST and PATCH, submit a JSON object as the body.

• Version header: Pass FOXY-API-VERSION: 1 with every request.

• Successful requests: A 200 status code means success, with a JSON payload.

• Errors: Non-2XX/3XX status codes, with a JSON body like:

  {
      "type": "authentication",
      "code": "422",
      "message": "`password` not defined or invalid."
  }

Authenticating

POST /s/customer/authenticate

Required fields: email, password.

fetch('https://foxy-demo.foxycart.com/s/customer/authenticate', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        "FOXY-API-VERSION": "1"
    },
    body: JSON.stringify({
        email: 'demo@example.com',
        password: 'demo12345'
    })
})
.then(response => response.json())
.then(data => console.log(data));

Response:

{
    "expires_in": 172800,
    "session_token": "cf9a7097-bc93-4ff0-8e47-986fffb4c380",
    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

• expires_in is the session lifetime in seconds, as configured in Foxy.

• jwt uses HS256 (shared secret) signing. This is optional — see JWT.io for details. Contact Foxy if you need a public/private keypair instead.

• session_token can be used to authenticate later requests as a Bearer token: Authorization: Bearer cf9a7097-bc93-4ff0-8e47-986fffb4c380.

Retrieving a customer

GET /s/customer

Optional parameters:

• zoom: default_billing_address, default_shipping_address, default_payment_method

• sso: returns an SSO URI as _links["fx:checkout"]. See Set up SSO between the customer portal and checkout.

Response fields include email, first_name, last_name, tax_id, id, is_anonymous, last_login_date, and date_created/date_modified, plus embedded resources like fx:attributes, fx:default_billing_address, fx:default_shipping_address, fx:default_payment_method, fx:transactions, and fx:subscriptions (when zoomed).

Modifying a customer

PATCH /s/customer

Accepted values in the JSON body:

• first_name, last_name, email, tax_id

• password: a new password (minimum 8 characters). Enforce any complexity requirements in your own UI.

• password_old: required if password is passed. Must match the current password, or a temporary password from a reset request.

• _embedded: can contain fx:default_billing_address, fx:default_shipping_address, fx:default_payment_method (must be zoomed to appear in the response). Note that cc_number is not updatable via the customer portal.

Response: matches a GET /s/customer response.

Retrieving transactions

GET /s/customer/transactions

Optional parameters:

• zoom: items, items:item_options

• limit (default 10), offset (default 0), order (default transaction_date desc) — see the API docs for details

Returns a paginated collection of transactions, each with a fx:receipt link and embedded fx:attributes.

Retrieving & modifying subscriptions

GET /s/customer/subscriptions

Optional parameters:

• zoom: transactions

• limit (default 10), offset (default 0), order (default next_transaction_date asc), is_active (default true) — see the API docs for details

Each subscription includes _embedded.template_config.allow_next_date_modification, a boolean indicating whether the customer can change the next charge date. This is returned per-subscription, though the underlying setting is store-wide.

PATCH /s/customer/subscriptions/SUBSCRIPTION_ID

Pre-requisites:

• Allow Next Date Modification must be enabled in the customer portal settings to modify next_transaction_date.

• Allow Frequency Modification must be configured as a JSONata query returning an array of allowed frequency values — for example, $contains(frequency, "m") allows ["1m","2m","3m","6m","1y"]. Only frequencies in the returned array can be patched. The subscription’s transaction_template (with items and item_options zoomed) is available to your JSONata query.

• The URI is returned in _links.self on the subscription object.

Response: the updated subscription object.

Notes

• Loyalty points example: This API can support a homegrown loyalty points system. Roughly: process the transaction webhook to calculate points earned (for example, based on the product total minus coupons), check the transaction’s attributes for a Loyalty_Points_Applied_On flag to avoid double-counting, then update a Loyalty_Points customer attribute (set visibility to public so it’s readable from the portal). To let customers redeem points, have your portal front-end call your own backend, which validates the request via the session JWT, creates a coupon code for a pre-existing coupon via the coupon codes API, and returns it to the customer to apply. This isn’t a built-in Foxy feature — it requires custom backend code.