This article covers the in-portal workflow for managing API keys on your account — creating them, naming them, rotating them, and revoking them. It does not cover the API itself.
#Where to find it
Open Settings in the side nav and choose API Keys.
#Creating an API key
Click Create a Key and fill in:
- Name — what this key is for ("HR system", "Order webhook", etc.)
- Description — anything else your team needs to know about it
When you save, the full key is shown to you once. Copy it immediately and store it somewhere safe — a password manager or your secrets vault. We do not store the raw key, so if you lose it you will need to create a new one.
#Using your key
Send the key as a bearer token on every request:
Authorization: Bearer <your-api-key>
For the full API reference — endpoints, request and response shapes, error codes — see Developers.
#Labeling and organizing keys
Most teams create one key per system that talks to Merch — one for the HR tool, one for the e-commerce store, one for a custom internal app. That way if you need to revoke a key, you know exactly which system goes dark.
Keep the Name descriptive and the Description specific. "Production webhook for HR onboarding" beats "key 3."
#Rate limits
Each API key is limited to roughly 1,000 requests per 24 hours by default. If your use case needs more, talk to your account team — we can raise the limit when there is a real need.
If you exceed the limit, you will get a 429 Too Many Requests response. Back off and retry later.
#Webhooks
Webhooks let your systems subscribe to event notifications (order status changes, shipping updates, campaign redemptions, invoice events) instead of polling. For the full setup, signing, and event reference, see Webhooks reference.
#Removing or rotating a key
From the API Keys table, hit the row's actions menu and choose Remove. The key stops working immediately — any system still using it will start getting 401 Unauthorized.
To rotate a key, create a new one, switch your systems over to it, and remove the old one. Most teams rotate keys at least once a year, and immediately if a teammate with access leaves.
#Getting help
API issues that look like ours and not yours, or just questions about how to model something, go to your account team. Send the request payload, the response, and what you expected — we will sort it out.