PerkShelf reseller API
Source products for your store or bot. List what you need, pay from a wallet or a purchase-sized invoice, then retrieve the delivered codes, links or account instructions.
https://perkshelf.dev/api/v1/buyerYour payment sender, our invoice and fulfillment
Our API returns a Wisetag and the exact USD amount to arrive. Your server or the Wise app sends the payment; PerkShelf does not accept your Wise credentials or move funds from your account. We confirm the signed incoming-credit event on our receiving profile.
Your integration pays the invoice from your own Wise account using your own Wise access. Once the payment arrives, our API automatically books and fulfills the purchase. You retain control of your payment sender and credentials.
Connect your store
- Create a website account and generate a key in Reseller API. Keep it on your server.
- Send Authorization: Bearer YOUR_KEY. Fetch products and use their PerkShelf IDs, prices and redemption information.
- Save one external_order_id before each purchase. Use it for every retry of that purchase, and a different ID for every new sale.
- Choose wallet purchase or just-in-time checkout. For an invoice, send exactly the returned amount on the selected rail/coin/network before its expiry.
- Poll every 10 seconds while payment or delivery is pending. Deliver each unit once using its invoice as your own deduplication key.
Endpoints
| Method | Path | Use |
|---|---|---|
| GET | /products | Product descriptions, account prices, availability and stock |
| GET | /products/{slug} | One product and its redemption instructions |
| GET | /balance | Your prepaid PerkShelf USD wallet |
| POST | /orders | Buy from your existing wallet using a unique external order ID |
| GET | /orders?external_order_id={id} | Retrieve the purchase batch and each delivered unit |
| GET | /orders/{invoice} | Read one invoice and delivery |
| GET | /orders | Cursor-paginated API order history |
| GET | /payment-methods | Available payment rails and network IDs |
| POST | /deposits | Create an idempotent wallet top-up invoice |
| GET | /deposits/{reference} | Read invoice status and exact payment instructions |
| POST | /deposits/{reference}/verify | Submit a crypto transaction ID; Wise waits for its signed webhook |
| DELETE | /deposits/{reference} | Cancel an unpaid invoice; this does not refund money |
| POST | /checkouts | Create a fixed-price product invoice without prefunding a large wallet |
| GET | /checkouts?external_order_id={id} | Read payment, order and delivery state |
The full guide and OpenAPI document cover filters, pagination, response fields, legacy /purchase compatibility and all payment endpoints.
Payment and delivery rules
- HTTP 202 means pending or reconciling. Check the saved external ID; do not create a new ID or pay again after a timeout.
- Wise amounts include the FX adjustment and matching cents; only the listed USD credit is available for the product. Crypto matching cents remain wallet credit.
- A payment invoice is not a stock reservation. A paid order stays pending if delivery needs a retry or operator review. Automatic delivery retries run every two minutes.
- API invoices expire after a 72-hour matching window. Cancel only unpaid invoices. Refunds require operator review and return to the PerkShelf wallet, not automatically to the sender’s Wise/crypto account.
- Each new wallet order requires an external ID. Order and payment reads are private to your account, including after API-key rotation.
Questions or a stuck payment? Open a support ticket with the invoice and external ID. Never send your API key in a ticket.