v0.1.4

Build on your weekly pack

Weekwright product API (v1). Public docs use stores/packs/billing vocabulary.

Base URL

Productionhttps://api.weekwright.io/v1

Staginghttps://api.staging.weekwright.io/v1

Every route is served at the root and under /v1. The server picker above updates every example on this page.

Authentication

Sign in with POST /session. The response sets a session cookie that is HttpOnly, Secure, and host-only. Send it back with every call; from a browser, use credentials: 'include'.

The session is bound to one account, chosen by the server. A request cannot name an account or a list of stores, so there is nothing to pass and nothing to guess. Sessions last seven days.

curl

# sign in once, keep the cookie, then call anything
curl -sS -X POST "$BASE/session" -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"demo-pass"}'

curl -sS "$BASE/me" -b cookies.txt

The demo account above exists only on a local API. Use your own account on staging or production.

Conventions

JSON in, JSON out. Bodies are limited to 1 MiB. Unknown fields on write calls are rejected.
Money is an integer in minor units plus an ISO 4217 code, like {"amountMinor": 1248000, "currency": "USD"}. Amounts are never summed across currencies.
Dates. Timestamps are RFC 3339 in UTC. A report's week start and end are calendar dates.
IDs are UUIDs. A malformed ID returns 400.
Pages. List calls take limit and cursor; pass back the cursor you were given.

Errors

Failures use the usual HTTP status and one body shape. Branch on error.code; show error.message to a person.

Error body

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Status	Meaning
`400`	The request was malformed.
`401`	Not signed in, or the session ended. Sign in again.
`403`	Signed in, but not a member of the account that owns this.
`404`	Not found, or not visible to your account.
`422`	The request was understood but a value is not acceptable.
`429`	Too many attempts. Wait for the number of seconds in `Retry-After`.

Account

Sign in and start a session

POST/session No sign-in #

Checks the email and password and sets the host-only session cookie (HttpOnly, Secure, SameSite=Lax, Path=/, no Domain attribute). The session is bound to the account the server picks for the user. The request cannot name an account. Sessions last seven days. Same empty 204 as POST /signup. Email is compared after trimming and lower-casing. A wrong password and an unknown email both return 401 with the same message, so the response does not reveal which emails are registered. Calls are limited per TCP peer, and an email with repeated wrong passwords is locked for a while, even if the next password is right. Both limits return 429 with Retry-After, set no cookie, and live in process memory, so they are not shared across API replicas.

Request body

Field	Type	Description
`email`required	string · email
`password`required	string · password

Responses

Signed in and session cookie set. No response body.

Empty body.

Bad request

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Not a member of the owning account / shop

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Too many sign-in attempts from this client or for this email

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

curl

curl -sS -X POST "$BASE/session" \
  -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"a-long-passphrase"}'

weekwright CLI

weekwright create-session --dry-run …

Sign out

DELETE/session No sign-in #

Ends the current session and clears the session cookie. Safe to call when already signed out: it still returns 204.

Responses

Signed out and session cookie cleared. No response body.

Empty body.

Create an account and start a session

POST/signup No sign-in #

Creates the account, an owner user, and a 14-day trial, then sets the host-only session cookie (HttpOnly, Secure, SameSite=Lax, Path=/, no Domain attribute). Same empty 204 as POST /session. Email is marked verified until an email verification mailer exists. Password length is 8–72 characters. A duplicate email returns 409. Calls are limited per TCP peer by an in-process counter so a public origin cannot flood account creation. The limit is not shared across API replicas and does not use X-Forwarded-For.

Request body

Field Type Description

emailrequired string · email

passwordrequired

string · password

min length 8 · max length 72

name

string

Account and profile name. Omitted or blank uses the email local-part, or "My store" when that is empty.

max length 200

Responses

Bad request

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Not a member of the owning account / shop

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

The email is already registered

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Validation failed

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Too many attempts from this client

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

curl

curl -sS -X POST "$BASE/signup" \
  -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"a-long-passphrase","name":"name"}'

weekwright CLI

weekwright signup --dry-run …

Get current user profile

GET/me Needs sign-in #

Responses

Profile

Returns UserProfile

Field	Type	Description
`id`required	string · uuid
`email`required	string · email
`name`	string · nullable
`accountId`	string · uuid	Tenant account bound to the session

Example response

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "email": "[email protected]",
  "name": "name",
  "accountId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40"
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Update profile

PATCH/me Needs sign-in #

Changing email clears emailVerified and requires re-verification before the new address is treated as verified. Prevents silent inbox takeover from a stolen session.

Request body

Field	Type	Description
`name`	string
`email`	string · email

Responses

Updated profile

Returns UserProfile

Field	Type	Description
`id`required	string · uuid
`email`required	string · email
`name`	string · nullable
`accountId`	string · uuid	Tenant account bound to the session

Example response

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "email": "[email protected]",
  "name": "name",
  "accountId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40"
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Validation failed

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

curl

curl -sS -X PATCH "$BASE/me" \
  -b cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"name":"name","email":"[email protected]"}'

weekwright CLI

weekwright patch-me --dry-run …

Change password

POST/me/password Needs sign-in #

Request body

Field	Type	Description
`currentPassword`required	string · password
`newPassword`required	string · password

Responses

Password changed

Empty body.

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Validation failed

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

curl

curl -sS -X POST "$BASE/me/password" \
  -b cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"currentPassword":"a-long-passphrase","newPassword":"a-long-passphrase"}'

weekwright CLI

weekwright change-password --dry-run …

Onboarding and account status for routing

GET/me/status Needs sign-in #

Frontend routes off onboarding.step. Waiting UI may poll this endpoint with a ceiling of ≥2–5s between polls (no sub-second polling). firstReport.message is always a client-safe mapped string (never raw vendor errors).

Responses

Status

Returns MeStatus

Field Type Description

accountIdrequired

string · uuid

Tenant account for this session (same as UserProfile.accountId)

emailrequired string · email

emailVerifiedrequired boolean

billingrequired

BillingStatus

Show fields

Field	Type	Description
`status`required	string	`nonetrialingactivepast_duecanceled`
`trialEndsAt`	string · date-time · nullable
`currentPeriodEndsAt`	string · date-time · nullable

shoprequired

ShopSummary

Show fields

Field	Type	Description
`id`	string · uuid · nullable
`connected`required	boolean
`shopDomain`	string · nullable	Store domain for display; not a vendor brand in UI copy
`connectedAt`	string · date-time · nullable

onboardingrequired

Onboarding

Show fields

Field Type Description

steprequired

string

verify_emailbillingconnect_shopwaiting_first_reportcomplete

firstReportrequired

FirstReportStatus

v1: account-scoped on MeStatus.onboarding.firstReport. Phase B: moves under the active shop; do not assume account-scoped forever.

Show fields

Field	Type	Description
`state`required	string	`not_startedqueuedgeneratingreadyfailed`
`reportId`	string · uuid · nullable
`expectedAt`	string · date-time · nullable
`message`	string · nullable	Client-safe status/error string only

Example response

{
  "accountId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "email": "[email protected]",
  "emailVerified": true,
  "billing": {
    "status": "none",
    "trialEndsAt": "2026-03-09T07:00:00Z",
    "currentPeriodEndsAt": "2026-03-09T07:00:00Z"
  },
  "shop": {
    "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
    "connected": true,
    "shopDomain": "cozy-goods.example",
    "connectedAt": "2026-03-09T07:00:00Z"
  },
  "onboarding": {
    "step": "verify_email",
    "firstReport": {
      "state": "not_started",
      "reportId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
      "expectedAt": "2026-03-09T07:00:00Z",
      "message": "That report was not found."
    }
  }
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Stores overview with rollup totals

GET/account/overview Needs sign-in #

Shop set is derived server-side from session accountId + membership. Totals use latest ready report per store; waiting stores appear in stores[] but are omitted from rollup math. Never sum across currencies — use totalsByCurrency[]. Responses should carry short TTL Cache-Control (e.g. private, max-age=30–60) so multi-store home does not amplify load.

Responses

Overview

Returns AccountOverview

Field Type Description

totalsrequired

AccountOverviewTotals

No single cross-currency revenue sum. Roll up per currency only.

Show fields

Field Type Description

storeCountReadyrequired integer

totalsByCurrencyrequired

array of CurrencyTotals

Show fields

Field Type Description

currencyrequired

string

ISO 4217

min length 3 · max length 3

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

ordersrequired integer

storesrequired

array of StoreOverviewItem

Show fields

Field Type Description

idrequired string · uuid

namerequired

string

Customer-facing store name

statusrequired

string

readywaitingfaileddisconnected

latestReady

StoreLatestReady · nullable

Show fields

Field Type Description

reportIdrequired string · uuid

weekStartrequired string · date

weekEndrequired string · date

summaryLinerequired string

revenue

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

orders integer

Example response

{
  "totals": {
    "storeCountReady": 0,
    "totalsByCurrency": [
      {
        "currency": "USD",
        "revenue": {
          "amountMinor": 1248000,
          "currency": "USD"
        },
        "orders": 0
      }
    ]
  },
  "stores": [
    {
      "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
      "name": "name",
      "status": "ready",
      "latestReady": {
        "reportId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
        "weekStart": "2026-03-09",
        "weekEnd": "2026-03-09",
        "summaryLine": "summaryLine",
        "revenue": {
          "amountMinor": 1248000,
          "currency": "USD"
        },
        "orders": 0
      }
    }
  ]
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Not a member of the owning account / shop

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Billing

Create billing checkout redirect

POST/billing/checkout-session Needs sign-in #

Returns an opaque URL. Client must not assume a specific payment vendor.

Parameters

Name Where and type Description

Idempotency-Key

header · string

Optional. Retries with the same key must not double-create sessions.

max length 255

Responses

Redirect URL

Returns RedirectUrl

Field	Type	Description
`url`required	string · uri	Opaque redirect URL

Example response

{
  "url": "https://example.com/"
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Create billing portal redirect

POST/billing/portal-session Needs sign-in #

Returns an opaque URL for managing payment methods and invoices. An account that has not finished checkout yet has nothing to manage and gets 409 no_subscription.

Parameters

Name Where and type Description

Idempotency-Key

header · string

Optional. Retries with the same key must not double-create sessions.

max length 255

Responses

Redirect URL

Returns RedirectUrl

Field	Type	Description
`url`required	string · uri	Opaque redirect URL

Example response

{
  "url": "https://example.com/"
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

The account has not started a plan, so there is nothing to manage yet

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Store

Start store connect flow

GET/shop/connect Needs sign-in #

Returns an opaque authorize URL. Uses signed state server-side (CSRF-proof).

Responses

Authorize URL

Field	Type	Description
`authorizeUrl`required	string · uri

Example response

{
  "authorizeUrl": "https://example.com/"
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Current store connection

GET/shop/connection Needs sign-in #

Responses

Connection

Returns ShopConnection

Field	Type	Description
`id`	string · uuid · nullable	Same id as ShopSummary.id / stores[].id
`connected`required	boolean
`shopDomain`	string · nullable
`connectedAt`	string · date-time · nullable
`scopes`	array of string

Example response

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "connected": true,
  "shopDomain": "cozy-goods.example",
  "connectedAt": "2026-03-09T07:00:00Z",
  "scopes": [
    "scopes"
  ]
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Disconnect store

DELETE/shop/connection Needs sign-in #

Stops report jobs for the disconnected store. v1: single store per account. Phase B: require shopId query/body so disconnect cannot hit the wrong store.

Responses

Disconnected

Empty body.

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Reports

List weekly packs for the account

GET/reports Needs sign-in #

AuthZ via account membership and shop ownership. Optional shopId filter for drill-in.

Parameters

Name Where and type Description

shopId query · string · uuid

limit

query · integer

Sidebar Recent reports uses limit=5.

min 1 · max 100 · default 5

cursor query · string

Responses

Report list

Returns ReportList

Field Type Description

itemsrequired

array of ReportListItem

Show fields

Field	Type	Description
`id`required	string · uuid
`shopId`required	string · uuid
`weekStart`required	string · date
`weekEnd`required	string · date
`status`required	string	`readyfailed`
`summaryLine`	string · nullable
`createdAt`required	string · date-time

nextCursor string · nullable

Example response

{
  "items": [
    {
      "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
      "shopId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
      "weekStart": "2026-03-09",
      "weekEnd": "2026-03-09",
      "status": "ready",
      "summaryLine": "summaryLine",
      "createdAt": "2026-03-09T07:00:00Z"
    }
  ],
  "nextCursor": "nextCursor"
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Not a member of the owning account / shop

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Resource not found

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Weekly pack detail

GET/reports/{reportId} Needs sign-in #

Bound to owning account via shop ownership (no IDOR). Sections mirror email: summary → sales → traffic → ops. weekAction is shop-scoped; not included on account overview.

Parameters

Name	Where and type	Description
`reportId`required	path · string · uuid

Responses

Report detail

Returns ReportDetail

Field Type Description

idrequired string · uuid

shopIdrequired string · uuid

weekStartrequired string · date

weekEndrequired string · date

statusrequired

string

readyfailed

summaryLine string · nullable

weekAction

WeekAction

This week's action — verb-led, numeric title + optional why

Show fields

Field	Type	Description
`title`required	string
`detail`	string · nullable
`sku`	string · nullable
`metric`	string · nullable

salesrequired

ReportSales

Show fields

Field Type Description

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

ordersrequired integer

aovrequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

revenueChangePctrequired number · double

topProductsrequired

array of TopProduct

Show fields

Field Type Description

titlerequired string

unitsrequired integer

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

trafficrequired

ReportTraffic

Show fields

Field Type Description

sessionsrequired integer

conversionRaterequired number · double

topChannelsrequired

array of TopChannel

Show fields

Field	Type	Description
`name`required	string
`sessions`required	integer

opsrequired

ReportOps

Show fields

Field Type Description

unfulfilledOrdersrequired integer

lowStockSkusrequired

array of LowStockSku

Show fields

Field	Type	Description
`sku`required	string
`title`required	string
`available`required	integer

returnsRatePct number · double · nullable

pdfUrl

string · uri · nullable

Short-lived signed URL or auth-gated proxy path. Never a durable public object URL. Still ownership-bound; never share across accounts.

createdAtrequired string · date-time

Example response

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "shopId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "weekStart": "2026-03-09",
  "weekEnd": "2026-03-09",
  "status": "ready",
  "summaryLine": "summaryLine",
  "weekAction": {
    "title": "Restock X · 8 left",
    "detail": "detail",
    "sku": "sku",
    "metric": "metric"
  },
  "sales": {
    "revenue": {
      "amountMinor": 1248000,
      "currency": "USD"
    },
    "orders": 0,
    "aov": {
      "amountMinor": 1248000,
      "currency": "USD"
    },
    "revenueChangePct": 0,
    "topProducts": [
      {
        "title": "title",
        "units": 0,
        "revenue": {
          "amountMinor": 1248000,
          "currency": "USD"
        }
      }
    ]
  },
  "traffic": {
    "sessions": 0,
    "conversionRate": 0,
    "topChannels": [
      {
        "name": "name",
        "sessions": 0
      }
    ]
  },
  "ops": {
    "unfulfilledOrders": 0,
    "lowStockSkus": [
      {
        "sku": "sku",
        "title": "title",
        "available": 0
      }
    ],
    "returnsRatePct": 0
  },
  "pdfUrl": "https://example.com/",
  "createdAt": "2026-03-09T07:00:00Z"
}

Not authenticated

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Not a member of the owning account / shop

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Resource not found

Returns Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example response

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

Models

Error

Field Type Description

errorrequired

object

Show fields

Field	Type	Description
`code`required	string
`message`required	string

Example

{
  "error": {
    "code": "not_found",
    "message": "That report was not found."
  }
}

RedirectUrl

Field	Type	Description
`url`required	string · uri	Opaque redirect URL

Example

{
  "url": "https://example.com/"
}

UserProfile

Field	Type	Description
`id`required	string · uuid
`email`required	string · email
`name`	string · nullable
`accountId`	string · uuid	Tenant account bound to the session

Example

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "email": "[email protected]",
  "name": "name",
  "accountId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40"
}

BillingStatus

Field	Type	Description
`status`required	string	`nonetrialingactivepast_duecanceled`
`trialEndsAt`	string · date-time · nullable
`currentPeriodEndsAt`	string · date-time · nullable

Example

{
  "status": "none",
  "trialEndsAt": "2026-03-09T07:00:00Z",
  "currentPeriodEndsAt": "2026-03-09T07:00:00Z"
}

ShopSummary

Field	Type	Description
`id`	string · uuid · nullable
`connected`required	boolean
`shopDomain`	string · nullable	Store domain for display; not a vendor brand in UI copy
`connectedAt`	string · date-time · nullable

Example

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "connected": true,
  "shopDomain": "cozy-goods.example",
  "connectedAt": "2026-03-09T07:00:00Z"
}

FirstReportStatus

v1: account-scoped on MeStatus.onboarding.firstReport. Phase B: moves under the active shop; do not assume account-scoped forever.

Field	Type	Description
`state`required	string	`not_startedqueuedgeneratingreadyfailed`
`reportId`	string · uuid · nullable
`expectedAt`	string · date-time · nullable
`message`	string · nullable	Client-safe status/error string only

Example

{
  "state": "not_started",
  "reportId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "expectedAt": "2026-03-09T07:00:00Z",
  "message": "That report was not found."
}

Onboarding

Field Type Description

steprequired

string

verify_emailbillingconnect_shopwaiting_first_reportcomplete

firstReportrequired

FirstReportStatus

v1: account-scoped on MeStatus.onboarding.firstReport. Phase B: moves under the active shop; do not assume account-scoped forever.

Show fields

Field	Type	Description
`state`required	string	`not_startedqueuedgeneratingreadyfailed`
`reportId`	string · uuid · nullable
`expectedAt`	string · date-time · nullable
`message`	string · nullable	Client-safe status/error string only

Example

{
  "step": "verify_email",
  "firstReport": {
    "state": "not_started",
    "reportId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
    "expectedAt": "2026-03-09T07:00:00Z",
    "message": "That report was not found."
  }
}

MeStatus

Field Type Description

accountIdrequired

string · uuid

Tenant account for this session (same as UserProfile.accountId)

emailrequired string · email

emailVerifiedrequired boolean

billingrequired

BillingStatus

Show fields

Field	Type	Description
`status`required	string	`nonetrialingactivepast_duecanceled`
`trialEndsAt`	string · date-time · nullable
`currentPeriodEndsAt`	string · date-time · nullable

shoprequired

ShopSummary

Show fields

Field	Type	Description
`id`	string · uuid · nullable
`connected`required	boolean
`shopDomain`	string · nullable	Store domain for display; not a vendor brand in UI copy
`connectedAt`	string · date-time · nullable

onboardingrequired

Onboarding

Show fields

Field Type Description

steprequired

string

verify_emailbillingconnect_shopwaiting_first_reportcomplete

firstReportrequired

FirstReportStatus

v1: account-scoped on MeStatus.onboarding.firstReport. Phase B: moves under the active shop; do not assume account-scoped forever.

Show fields

Field	Type	Description
`state`required	string	`not_startedqueuedgeneratingreadyfailed`
`reportId`	string · uuid · nullable
`expectedAt`	string · date-time · nullable
`message`	string · nullable	Client-safe status/error string only

Example

{
  "accountId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "email": "[email protected]",
  "emailVerified": true,
  "billing": {
    "status": "none",
    "trialEndsAt": "2026-03-09T07:00:00Z",
    "currentPeriodEndsAt": "2026-03-09T07:00:00Z"
  },
  "shop": {
    "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
    "connected": true,
    "shopDomain": "cozy-goods.example",
    "connectedAt": "2026-03-09T07:00:00Z"
  },
  "onboarding": {
    "step": "verify_email",
    "firstReport": {
      "state": "not_started",
      "reportId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
      "expectedAt": "2026-03-09T07:00:00Z",
      "message": "That report was not found."
    }
  }
}

ShopConnection

Field	Type	Description
`id`	string · uuid · nullable	Same id as ShopSummary.id / stores[].id
`connected`required	boolean
`shopDomain`	string · nullable
`connectedAt`	string · date-time · nullable
`scopes`	array of string

Example

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "connected": true,
  "shopDomain": "cozy-goods.example",
  "connectedAt": "2026-03-09T07:00:00Z",
  "scopes": [
    "scopes"
  ]
}

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

Example

{
  "amountMinor": 1248000,
  "currency": "USD"
}

TopProduct

Field Type Description

titlerequired string

unitsrequired integer

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

Example

{
  "title": "title",
  "units": 0,
  "revenue": {
    "amountMinor": 1248000,
    "currency": "USD"
  }
}

TopChannel

Field	Type	Description
`name`required	string
`sessions`required	integer

Example

{
  "name": "name",
  "sessions": 0
}

LowStockSku

Field	Type	Description
`sku`required	string
`title`required	string
`available`required	integer

Example

{
  "sku": "sku",
  "title": "title",
  "available": 0
}

WeekAction

This week's action — verb-led, numeric title + optional why

Field	Type	Description
`title`required	string
`detail`	string · nullable
`sku`	string · nullable
`metric`	string · nullable

Example

{
  "title": "Restock X · 8 left",
  "detail": "detail",
  "sku": "sku",
  "metric": "metric"
}

ReportListItem

Field	Type	Description
`id`required	string · uuid
`shopId`required	string · uuid
`weekStart`required	string · date
`weekEnd`required	string · date
`status`required	string	`readyfailed`
`summaryLine`	string · nullable
`createdAt`required	string · date-time

Example

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "shopId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "weekStart": "2026-03-09",
  "weekEnd": "2026-03-09",
  "status": "ready",
  "summaryLine": "summaryLine",
  "createdAt": "2026-03-09T07:00:00Z"
}

ReportList

Field Type Description

itemsrequired

array of ReportListItem

Show fields

Field	Type	Description
`id`required	string · uuid
`shopId`required	string · uuid
`weekStart`required	string · date
`weekEnd`required	string · date
`status`required	string	`readyfailed`
`summaryLine`	string · nullable
`createdAt`required	string · date-time

nextCursor string · nullable

Example

{
  "items": [
    {
      "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
      "shopId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
      "weekStart": "2026-03-09",
      "weekEnd": "2026-03-09",
      "status": "ready",
      "summaryLine": "summaryLine",
      "createdAt": "2026-03-09T07:00:00Z"
    }
  ],
  "nextCursor": "nextCursor"
}

ReportSales

Field Type Description

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

ordersrequired integer

aovrequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

revenueChangePctrequired number · double

topProductsrequired

array of TopProduct

Show fields

Field Type Description

titlerequired string

unitsrequired integer

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

Example

{
  "revenue": {
    "amountMinor": 1248000,
    "currency": "USD"
  },
  "orders": 0,
  "aov": {
    "amountMinor": 1248000,
    "currency": "USD"
  },
  "revenueChangePct": 0,
  "topProducts": [
    {
      "title": "title",
      "units": 0,
      "revenue": {
        "amountMinor": 1248000,
        "currency": "USD"
      }
    }
  ]
}

ReportTraffic

Field Type Description

sessionsrequired integer

conversionRaterequired number · double

topChannelsrequired

array of TopChannel

Show fields

Field	Type	Description
`name`required	string
`sessions`required	integer

Example

{
  "sessions": 0,
  "conversionRate": 0,
  "topChannels": [
    {
      "name": "name",
      "sessions": 0
    }
  ]
}

ReportOps

Field Type Description

unfulfilledOrdersrequired integer

lowStockSkusrequired

array of LowStockSku

Show fields

Field	Type	Description
`sku`required	string
`title`required	string
`available`required	integer

returnsRatePct number · double · nullable

Example

{
  "unfulfilledOrders": 0,
  "lowStockSkus": [
    {
      "sku": "sku",
      "title": "title",
      "available": 0
    }
  ],
  "returnsRatePct": 0
}

ReportDetail

Field Type Description

idrequired string · uuid

shopIdrequired string · uuid

weekStartrequired string · date

weekEndrequired string · date

statusrequired

string

readyfailed

summaryLine string · nullable

weekAction

WeekAction

This week's action — verb-led, numeric title + optional why

Show fields

Field	Type	Description
`title`required	string
`detail`	string · nullable
`sku`	string · nullable
`metric`	string · nullable

salesrequired

ReportSales

Show fields

Field Type Description

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

ordersrequired integer

aovrequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

revenueChangePctrequired number · double

topProductsrequired

array of TopProduct

Show fields

Field Type Description

titlerequired string

unitsrequired integer

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

trafficrequired

ReportTraffic

Show fields

Field Type Description

sessionsrequired integer

conversionRaterequired number · double

topChannelsrequired

array of TopChannel

Show fields

Field	Type	Description
`name`required	string
`sessions`required	integer

opsrequired

ReportOps

Show fields

Field Type Description

unfulfilledOrdersrequired integer

lowStockSkusrequired

array of LowStockSku

Show fields

Field	Type	Description
`sku`required	string
`title`required	string
`available`required	integer

returnsRatePct number · double · nullable

pdfUrl

string · uri · nullable

Short-lived signed URL or auth-gated proxy path. Never a durable public object URL. Still ownership-bound; never share across accounts.

createdAtrequired string · date-time

Example

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "shopId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "weekStart": "2026-03-09",
  "weekEnd": "2026-03-09",
  "status": "ready",
  "summaryLine": "summaryLine",
  "weekAction": {
    "title": "Restock X · 8 left",
    "detail": "detail",
    "sku": "sku",
    "metric": "metric"
  },
  "sales": {
    "revenue": {
      "amountMinor": 1248000,
      "currency": "USD"
    },
    "orders": 0,
    "aov": {
      "amountMinor": 1248000,
      "currency": "USD"
    },
    "revenueChangePct": 0,
    "topProducts": [
      {
        "title": "title",
        "units": 0,
        "revenue": {
          "amountMinor": 1248000,
          "currency": "USD"
        }
      }
    ]
  },
  "traffic": {
    "sessions": 0,
    "conversionRate": 0,
    "topChannels": [
      {
        "name": "name",
        "sessions": 0
      }
    ]
  },
  "ops": {
    "unfulfilledOrders": 0,
    "lowStockSkus": [
      {
        "sku": "sku",
        "title": "title",
        "available": 0
      }
    ],
    "returnsRatePct": 0
  },
  "pdfUrl": "https://example.com/",
  "createdAt": "2026-03-09T07:00:00Z"
}

StoreLatestReady

Field Type Description

reportIdrequired string · uuid

weekStartrequired string · date

weekEndrequired string · date

summaryLinerequired string

revenue

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

orders integer

Example

{
  "reportId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "weekStart": "2026-03-09",
  "weekEnd": "2026-03-09",
  "summaryLine": "summaryLine",
  "revenue": {
    "amountMinor": 1248000,
    "currency": "USD"
  },
  "orders": 0
}

StoreOverviewItem

Field Type Description

idrequired string · uuid

namerequired

string

Customer-facing store name

statusrequired

string

readywaitingfaileddisconnected

latestReady

StoreLatestReady · nullable

Show fields

Field Type Description

reportIdrequired string · uuid

weekStartrequired string · date

weekEndrequired string · date

summaryLinerequired string

revenue

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

orders integer

Example

{
  "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
  "name": "name",
  "status": "ready",
  "latestReady": {
    "reportId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
    "weekStart": "2026-03-09",
    "weekEnd": "2026-03-09",
    "summaryLine": "summaryLine",
    "revenue": {
      "amountMinor": 1248000,
      "currency": "USD"
    },
    "orders": 0
  }
}

CurrencyTotals

Field Type Description

currencyrequired

string

ISO 4217

min length 3 · max length 3

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

ordersrequired integer

Example

{
  "currency": "USD",
  "revenue": {
    "amountMinor": 1248000,
    "currency": "USD"
  },
  "orders": 0
}

AccountOverviewTotals

No single cross-currency revenue sum. Roll up per currency only.

Field Type Description

storeCountReadyrequired integer

totalsByCurrencyrequired

array of CurrencyTotals

Show fields

Field Type Description

currencyrequired

string

ISO 4217

min length 3 · max length 3

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

ordersrequired integer

Example

{
  "storeCountReady": 0,
  "totalsByCurrency": [
    {
      "currency": "USD",
      "revenue": {
        "amountMinor": 1248000,
        "currency": "USD"
      },
      "orders": 0
    }
  ]
}

AccountOverview

Field Type Description

totalsrequired

AccountOverviewTotals

No single cross-currency revenue sum. Roll up per currency only.

Show fields

Field Type Description

storeCountReadyrequired integer

totalsByCurrencyrequired

array of CurrencyTotals

Show fields

Field Type Description

currencyrequired

string

ISO 4217

min length 3 · max length 3

revenuerequired

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

ordersrequired integer

storesrequired

array of StoreOverviewItem

Show fields

Field Type Description

idrequired string · uuid

namerequired

string

Customer-facing store name

statusrequired

string

readywaitingfaileddisconnected

latestReady

StoreLatestReady · nullable

Show fields

Field Type Description

reportIdrequired string · uuid

weekStartrequired string · date

weekEndrequired string · date

summaryLinerequired string

revenue

MoneyAmount

Integer minor units + ISO 4217 currency (no floating-point money)

Show fields

Field Type Description

amountMinorrequired

integer · int64

Amount in the currency's minor units (e.g. cents)

currencyrequired

string

ISO 4217 currency code

min length 3 · max length 3

orders integer

Example

{
  "totals": {
    "storeCountReady": 0,
    "totalsByCurrency": [
      {
        "currency": "USD",
        "revenue": {
          "amountMinor": 1248000,
          "currency": "USD"
        },
        "orders": 0
      }
    ]
  },
  "stores": [
    {
      "id": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
      "name": "name",
      "status": "ready",
      "latestReady": {
        "reportId": "3f2b1c0e-8a54-4d7e-9a61-5c1d2e7b9f40",
        "weekStart": "2026-03-09",
        "weekEnd": "2026-03-09",
        "summaryLine": "summaryLine",
        "revenue": {
          "amountMinor": 1248000,
          "currency": "USD"
        },
        "orders": 0
      }
    }
  ]
}