API referenceShop handover

Shop handover

6 operations. Every schema and example on this page is generated from the platform contract.

Call it off: the claim link stops working.

The shop’s own login only. Calling off nothing changes nothing. Refused with `CLAIM_UNDERWAY` (409) when a claim got part-way (the login already carries his address): he finishes it from the same link. Answers the row as it then stands.

Parameters

store_idstring · uuidqueryrequired

Response, 200

availablebooleanrequired

False until the hand-over record exists on this server: the Account row stays hidden.

stateenumrequired

`none`: nothing sent (or the last one was called off). `sent`: a claim link that still works is out. `expired`: the link ran out unclaimed (Send again renews it). `claiming`: a claim got part-way and he has not finished it (the login already carries his address; Call it off is refused). `claimed`: handed over.

nonesentclaimingexpiredclaimed
toEmailstring, nullablerequired

Where the claim email went.

toFirstNamestring, nullablerequired
sentAtstring, nullablerequired

When the newest claim email went.

expiresAtstring, nullablerequired

When the link stops working.

claimedAtstring, nullablerequired
curl -X DELETE "https://www.membber.com/api/v1/shop-handover?store_id=6659c139-0000-4000-8000-d0c500000066" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678"
Response, 200
{
  "available": true,
  "state": "none",
  "toEmail": "alex@example.com",
  "toFirstName": "<toFirstName>",
  "sentAt": "<sentAt>",
  "expiresAt": "<expiresAt>",
  "claimedAt": "<claimedAt>"
}

Whether this shop has been handed over, or a claim email is out.

The shop’s own login only: staff, API keys and AI tools are refused (403).

Parameters

store_idstring · uuidqueryrequired

Response, 200

availablebooleanrequired

False until the hand-over record exists on this server: the Account row stays hidden.

stateenumrequired

`none`: nothing sent (or the last one was called off). `sent`: a claim link that still works is out. `expired`: the link ran out unclaimed (Send again renews it). `claiming`: a claim got part-way and he has not finished it (the login already carries his address; Call it off is refused). `claimed`: handed over.

nonesentclaimingexpiredclaimed
toEmailstring, nullablerequired

Where the claim email went.

toFirstNamestring, nullablerequired
sentAtstring, nullablerequired

When the newest claim email went.

expiresAtstring, nullablerequired

When the link stops working.

claimedAtstring, nullablerequired
curl -G "https://www.membber.com/api/v1/shop-handover" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  --data-urlencode "store_id=6659c139-0000-4000-8000-d0c500000066"
Response, 200
{
  "available": true,
  "state": "none",
  "toEmail": "alex@example.com",
  "toFirstName": "<toFirstName>",
  "sentAt": "<sentAt>",
  "expiresAt": "<expiresAt>",
  "claimedAt": "<claimedAt>"
}

Hand this shop over: send its owner a claim email.

The shop’s own login only (staff, API keys and AI tools are refused), and only a login with this one shop. Nothing moves until the owner claims. The sender’s own password is checked first: `PASSWORD_REQUIRED` (400), `WRONG_PASSWORD` (403), `PASSWORD_LOGIN_REQUIRED` (403, an Apple or Google login has none: “Hand-over needs a password login”). On every send the login’s CURRENT sign-in address also gets a plain notice (masked new address, no button), never the new owner. Refused: `HANDOVER_OPEN` (409, a claim link is already out: send again or call it off), `SAME_EMAIL` (400), `EMAIL_TAKEN` (409, another Membber account has that email), `MORE_THAN_ONE_SHOP` (409), `ALREADY_HANDED_OVER` (409), `NOT_AVAILABLE` (503), `EMAIL_NOT_SENT` (502). Five an hour per shop.

Request body

store_idstring · uuidrequired
emailstringrequired

The owner’s email. On claim it becomes the sign-in email and the shop’s public email.

firstNamestringrequired

The owner’s first name, for the email and the page.

passwordstringoptional

The sender’s CURRENT password, checked before anything else is looked up. Required (`PASSWORD_REQUIRED`, 400, when missing).

Response, 200

availablebooleanrequired

False until the hand-over record exists on this server: the Account row stays hidden.

stateenumrequired

`none`: nothing sent (or the last one was called off). `sent`: a claim link that still works is out. `expired`: the link ran out unclaimed (Send again renews it). `claiming`: a claim got part-way and he has not finished it (the login already carries his address; Call it off is refused). `claimed`: handed over.

nonesentclaimingexpiredclaimed
toEmailstring, nullablerequired

Where the claim email went.

toFirstNamestring, nullablerequired
sentAtstring, nullablerequired

When the newest claim email went.

expiresAtstring, nullablerequired

When the link stops working.

claimedAtstring, nullablerequired
curl -X POST "https://www.membber.com/api/v1/shop-handover" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "6659c139-0000-4000-8000-d0c500000066",
    "email": "alex@example.com",
    "firstName": "Alex"
  }'
Response, 200
{
  "available": true,
  "state": "none",
  "toEmail": "alex@example.com",
  "toFirstName": "<toFirstName>",
  "sentAt": "<sentAt>",
  "expiresAt": "<expiresAt>",
  "claimedAt": "<claimedAt>"
}

Claim the shop: the set-up login becomes his, and stops working for anybody else.

With a new password (8 or more characters), or an Apple or Google ID token (verified like /api/v1/auth/id-token, its email confirmed by the provider; an Apple relay address still claims: the link proves it is him). The sign-in email and the shop’s public email become the address the link was sent to, every other session is signed out, and a session is answered for the browser to keep. Refused with words, never a 500: `EXPIRED` (410), `CANCELLED` (410), `CLAIMED` (409, log in with your email), `EMAIL_TAKEN` (409, the address the link went to is taken; moves nothing), `PROVIDER_EMAIL_TAKEN` (409, the Apple or Google account he picked belongs to another Membber account; the link is still open, moves nothing), `WEAK_PASSWORD` (400), `PASSWORD_TOO_LONG` (400, over 72 bytes), `PASSWORD_REJECTED` (400, the sign-in service refused that password: pick another), `TOKEN_INVALID` (401), `EMAIL_NOT_VERIFIED` (403), `BUSY` (409, a claim is already moving it). A passing fault (503) spends nothing, so Try again works. Same origin only. PUBLIC: the token is the proof.

auth none, publicop claimShopHandoveridempotent retryrate limitederrors

Request body

tokenstringrequired
wayanyrequired

Response, 200

sessionobjectrequired
2 child fields
access_tokenstringrequired
refresh_tokenstringrequired
userobjectrequired
2 child fields
idstringrequired
emailstring, nullablerequired
emailstringrequired

The address he signs in with from now on.

landingstringrequired

Where Go to your shop goes.

curl -X POST "https://www.membber.com/api/v1/shop-handover/claim" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<token>",
    "way": "<way>"
  }'
Response, 200
{
  "session": {
    "access_token": "<access_token>",
    "refresh_token": "<refresh_token>"
  },
  "user": {
    "id": "00000d1b-0000-4000-8000-d0c500000000",
    "email": "alex@example.com"
  },
  "email": "alex@example.com",
  "landing": "<landing>"
}

What a claim link is for: the shop and where it stands. Moves nothing.

A POST, so the token rides in a body and never in an address. Same origin only. Never the whole email address. PUBLIC: the token is the proof.

auth none, publicop previewShopHandoveridempotent retryrate limitederrors

Request body

tokenstringrequired

Response, 200

stateenumrequired

`unknown`: not a link this server made. `cancelled`: called off, or sent again (an older link).

openexpiredcancelledclaimedunknown
shopNamestring, nullablerequired
logoUrlstring, nullablerequired
ribbonColorstring, nullablerequired

The shop’s own colour (`stores.primary_color`).

firstNamestring, nullablerequired

Only while the link works.

maskedEmailstring, nullablerequired

Only while the link works, and never whole: `o•••@friendsoneverystreet.co.uk`.

shopobjectrequired

Only while the link works: what the page shows him once it is his.

5 child fields
addressstring, nullablerequired

Her shop’s address, `name.membber.com`.

itemsintegerrequired

Her items on Membber now.

livebooleanrequired
photoUrlstring, nullablerequired

One of her own item photos, or null.

photoAltstring, nullablerequired
curl -X POST "https://www.membber.com/api/v1/shop-handover/claim/preview" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<token>"
  }'
Response, 200
{
  "state": "open",
  "shopName": "<shopName>",
  "logoUrl": "https://example.com/image.jpg",
  "ribbonColor": "<ribbonColor>",
  "firstName": "Alex",
  "maskedEmail": "alex@example.com",
  "shop": {
    "address": "<address>",
    "items": 0,
    "live": true,
    "photoUrl": "https://example.com/image.jpg",
    "photoAlt": "<photoAlt>"
  }
}

Send the claim email again, with a new link that works for 7 days.

The old link stops working the moment the new one is sent; a send that fails keeps the old one working. A minute between sends, five a day. Refused: `NO_HANDOVER` (404), `TOO_SOON` (429), `RATE_LIMITED` (429), `EMAIL_NOT_SENT` (502).

Request body

store_idstring · uuidrequired

Response, 200

availablebooleanrequired

False until the hand-over record exists on this server: the Account row stays hidden.

stateenumrequired

`none`: nothing sent (or the last one was called off). `sent`: a claim link that still works is out. `expired`: the link ran out unclaimed (Send again renews it). `claiming`: a claim got part-way and he has not finished it (the login already carries his address; Call it off is refused). `claimed`: handed over.

nonesentclaimingexpiredclaimed
toEmailstring, nullablerequired

Where the claim email went.

toFirstNamestring, nullablerequired
sentAtstring, nullablerequired

When the newest claim email went.

expiresAtstring, nullablerequired

When the link stops working.

claimedAtstring, nullablerequired
curl -X POST "https://www.membber.com/api/v1/shop-handover/resend" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "6659c139-0000-4000-8000-d0c500000066"
  }'
Response, 200
{
  "available": true,
  "state": "none",
  "toEmail": "alex@example.com",
  "toFirstName": "<toFirstName>",
  "sentAt": "<sentAt>",
  "expiresAt": "<expiresAt>",
  "claimedAt": "<claimedAt>"
}
WhatsApp
Book a Call
Get Started
Shop handover API | Membber Developers