Skip to content

Approve requests and run a waitlist

Have buyers ask before they get a product, approve or decline each request, and let guests into a full event from its waitlist.

Updated

A product can require your approval: a buyer’s get becomes a request you approve or decline, and they hold the product only once you approve. A paid one is charged only once you approve: on the card they saved at checkout, or by taking the amount held on their card. An event can also keep a waitlist, which guests join once it’s full and you let them in from as seats free. This guide turns both on and works the requests. It uses the sherpo helper from your first call and a token with product:write to change the settings, customer:read to list requests and customer:write to decide them.

Turn approval on

Any product takes settings.approval: none (the default) or required, and settings.approval_payment, how a paid request waits: saved_card (the default) or hold. An event takes settings.event.waitlist too, true to open a waitlist once it’s full. Set both with PATCH /products/{product}:

curl -X PATCH 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: approval-meetup' \
  -H 'Content-Type: application/json' \
  -d '{
  "settings": {
    "approval": "required",
    "event": {
      "waitlist": true
    }
  }
}'
const answer = await sherpo('PATCH', '/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e', {
  body: {
    "settings": {
      "approval": "required",
      "event": {
        "waitlist": true
      }
    }
  },
  key: 'approval-meetup',
});

Answers 200, abridged:

{
  "id": "5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e",
  "category": "event",
  "settings": {
    "approval": "required",
    "event": {
      "waitlist": true
    }
  }
}

A request is one purchase you decide, so a product that requires approval sells one-time prices only, free or paid. Turning approval on while a recurring price is on sale answers invalid at settings.approval: archive those prices first. While it’s on, creating or restoring a recurring price answers invalid at kind (or price).

What a buyer’s get becomes

A buyer gets the product through checkout as for any price, and the order is recorded, but no access is granted. The checkout settles into a request, pending, and the buyer is told it was sent.

At a paid price, checkout saves the buyer’s card and charges nothing: the order is recorded unpaid, and the request’s payment reads saved. With approval_payment hold, checkout instead holds the total on a card (an authorization, cards only) and the request’s payment reads held, with hold_expires_at saying when the hold is released. Card holds last about 7 days, so one you haven’t decided a day before its card lapses is released: the request is declined with closed_reason expired, its seats go back on sale, nothing is charged and the buyer is told. A cart holding such a line holds nothing else, so one charge pays one request. A line a coupon takes down to nothing waits as a free request, with no card saved. On an event, the order holds its seats while the request waits, so a pending guest counts against the capacity as a sale does and nobody else takes their seat.

The buyer reads where they stand on the product itself: the customer API’s product read carries their latest request and its status (see Checkout).

List the requests

GET /products/{product}/requests pages a product’s requests, oldest first:

curl -g 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/requests?filter[status]=pending&facets=status' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/requests', {
  query: [
    ['filter[status]', 'pending'],
    ['facets', 'status'],
  ],
});

Answers 200, abridged:

{
  "items": [
    {
      "id": "8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b",
      "product_id": "5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e",
      "customer_id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
      "status": "pending",
      "tier": {
        "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6a",
        "name": "In person",
        "rank": 2
      },
      "price_id": "3d2c1b0a-9f8e-4d7c-9b6a-5e4d3c2b1a09",
      "quantity": 2,
      "order_item_id": "6c5d4e3f-2a1b-4c0d-9e8f-7a6b5c4d3e2f",
      "grant_id": null,
      "created_at": "2026-11-02T18:40:00.000Z",
      "decided_at": null,
      "customer": {
        "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "phone": null,
        "erased": false
      },
      "answers": [
        {
          "question_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
          "value": "+39 333 123 4567"
        }
      ]
    }
  ],
  "cursor": null,
  "facets": {
    "status": {
      "pending": 1,
      "waitlisted": 3,
      "approved": 12,
      "declined": 2
    }
  }
}
  • status is pending (waiting for your decision), waitlisted (on an event’s waitlist, waiting for a seat), approved or declined; decided_at says when you decided, and closed_reason is expired for one declined because its hold was released before you decided.
  • payment is a paid request’s: saved while its card waits to be charged, held while its total is held on the card, charging once you approved it, due once its charge failed or found no saved card, so the buyer pays it themselves; null for a free request, and once decided.
  • tier and price_id are what the buyer asked for, and quantity how many tickets. order_item_id is the order line that asked, or the one a promotion recorded; null while on a waitlist. grant_id is the grant an approval gave.
  • answers are the buyer’s answers to the product’s registration questions, in the questions’ order, so you can decide on what they told you. A waitlisted guest joined without checkout, so they have answers only from an earlier purchase, and a declined buyer’s answers are dropped soon after, unless something else they hold keeps them. Without customer:read, as on a token that only decides requests, a request names no customer and no answers.
  • search matches the buyer’s name, email or phone.
  • Filters take customer_id, status, tier_id and created_at.
  • Sorts are created (the default, oldest first) and latest, and facets=status counts the requests by each.

Approve or decline

POST /products/{product}/requests/{request}/approve approves a pending request. The buyer is granted what they asked for from then on, on the seats their order holds, and told (a buyer who already holds a ticket of their own as high keeps it as their access, while the request’s seats stay its own order’s until that order is refunded whole; a guest ticket someone bought them never stands in, so they get one of their own, which a whole refund of the order ends when refunds remove access):

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/requests/8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b/approve' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: approve-8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/requests/8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b/approve', {
  key: 'approve-8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b',
});

Answers 200, abridged:

{
  "id": "8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b",
  "status": "approved",
  "order_item_id": "6c5d4e3f-2a1b-4c0d-9e8f-7a6b5c4d3e2f",
  "grant_id": "0d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "decided_at": "2026-11-03T09:05:00.000Z"
}

Approving a paid request charges the card it saved, off session, and answers it pending with payment charging: once the charge goes through, its order is paid and the request reads approved, as above, with the buyer emailed. Approving a held request takes the amount held instead, with no new charge. A charge the card refuses, a hold that can no longer be taken, or one that would need the buyer (as a bank’s check of a payment does), leaves the request pending with payment due, and the buyer is emailed a link to pay it with another card; once they do, it’s approved. Approving a due request charges its card again; while the buyer is paying it themselves, approving answers conflict on request with current paying. While a charge is under way, approving answers conflict on request with current charging, but you can still decline: the charge is called off, or given back once it lands. Its order reads nothing paid until the charge pays it, so a declined request moves none of your takings.

POST /products/{product}/requests/{request}/decline declines a pending request or a waitlist place. Any seats it held go back on sale, nothing is charged (a paid request’s coupon is given back too, and a hold on its card is released), and the buyer is told:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/requests/8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b/decline' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: decline-8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/requests/8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b/decline', {
  key: 'decline-8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b',
});

Answers 200, abridged:

{
  "id": "8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b",
  "status": "declined",
  "grant_id": null,
  "decided_at": "2026-11-03T09:05:00.000Z"
}

The grant an approval gives is yours, as one you grant is: its source is manual, naming the request. A paid request’s grant is its charge’s: its source is checkout, with the settlement its payment made, so a refund of it treats access as any sale’s does. While the store has no Stripe account to charge through, or when a charge is given back before it settles, the request goes back to payment saved, and you can approve it again once that’s mended. Once an event’s last session ended, or it was canceled, nothing is charged for it: approving a paid request answers conflict on request with current closed and reason the event has ended, a charge still waiting puts the request back to payment saved, and the buyer can no longer pay a due one, so decline it to give its seats back. A buyer who already holds what they asked for, say because you granted it meanwhile, isn’t granted again or charged, and the request reads approved with that grant. While the store’s new unlocks are paused, approving and promoting answer not_permitted with reason paused.

Each answers the request as it now stands. A request that isn’t in the status a decision takes (approving one already decided, or one on the waitlist) answers conflict on status, with current its status. Both take an Idempotency-Key, so a retry answers the first decision again.

Run an event’s waitlist

With settings.event.waitlist on, a guest who asks for a one-time ticket while the seats they ask for are gone joins the waitlist instead, through the customer API’s joinWaitlist. They’re waitlisted, hold no seat, and are told they’re on it. Nobody joins while seats are left, and a plan has no waitlist.

Once seats free, from a declined request, a refund that ends a ticket or a higher capacity, POST /products/{product}/requests/{request}/promote lets a waitlisted guest in:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/requests/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/promote' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: promote-1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/5c4b3a29-1807-4f6e-8d5c-4b3a29180f7e/requests/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/promote', {
  key: 'promote-1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e',
});

Answers 200, abridged:

{
  "id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
  "status": "approved",
  "quantity": 1,
  "order_item_id": "6c5d4e3f-2a1b-4c0d-9e8f-7a6b5c4d3e2f",
  "grant_id": "0d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "decided_at": "2026-11-04T16:20:00.000Z"
}

A promotion records an order for the ticket they asked for, which takes the seats. A free ticket is granted at once, with no approval step after it: the request reads approved with that order’s line in order_item_id. A paid one reads pending with payment charging, its seats held, and is charged as an approval is, at the price they joined at: on the card the guest saved for their place when they joined (the customer API’s saveWaitlistCard), else on their default saved card. A waitlist place never holds an amount on a card, whatever approval_payment says, as the wait can outlast a hold. With no saved card, its payment is due and the guest is emailed a link to pay for their seat. The order is like one you record, sent as order.created. While the event still lacks the seats, it answers conflict on items, with current the seats left. Once the ticket they waited for is no longer on sale at the price they joined at (its price archived or changed, or the event discontinued), it answers conflict on request with current closed, and the place can only be declined. Declining a waitlist place takes them off the list. A guest who buys a freed seat themselves, or whom another buyer names on a ticket while they wait for one, leaves the waitlist as approved, on that grant, and endpoints are sent request.approved; a ticket of a lower type than the one they wait for leaves them waiting. If that buyer later hands the ticket to someone else, or it’s refunded, before the event starts, the guest is back on the waitlist in their place (endpoints are sent request.waitlisted), unless they hold another ticket as high, which the place moves to. While an ask of their own waits for your decision, the place stays closed; declining that ask puts them back on the waitlist, and endpoints are sent request.waitlisted. One whose purchase gives access only later, as a plan starting ahead, stays on the waitlist until you let them in. A promotion takes no other seat only once a grant of their own (not a guest ticket) gives them the awaited ticket for good; a dated one, as a plan’s, doesn’t, so their promotion takes a seat like anyone’s.

A price, ticket type or event that a waiting request names can’t be deleted until you decide the request: the delete answers conflict naming product_request in blocked_by.

On the guest list

An event’s guest list shows each request’s guest as it stands: pending while their request waits and waitlisted while they’re on the waitlist, both with grant_id null, then going once approved or promoted. A declined guest is canceled with cancel_reason declined. A waitlisted guest’s source is waitlist. The guest list’s stats count pending and waitlisted apart from going.

Webhooks

Six events follow a request, each with the customer, the request as the list reads it (its answers as they stand when the event is first sent), and its product (see Webhooks):

Event Sent when
request.received A buyer’s get of a product that requires approval waits for you.
request.waitlisted A guest joins a full event’s waitlist.
request.approved You approve a request or promote a waitlisted guest.
request.declined You decline a request or a waitlist place.
request.expired A paid request’s card hold was released a day before it lapsed, as you hadn’t decided it.
request.payment_due The charge of a paid request you approved or promoted failed or found no saved card, so the buyer is asked to pay.

The buyer gets an email for each too, which you can change on the merchant app’s customer messages.

Type to search…

↑↓ navigate↵ selectEsc close