An API key is the credential your code uses to call the Merch REST API on your account's behalf. This article covers creating them, sending them on each request, rotating them, and the rate limits that apply.
#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>
The full API reference is available from your account team. We have endpoints for orders, products, inventory, campaigns, recipients, contacts, and webhooks.
#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."
#IP whitelisting
If your integration runs from a known set of servers, you can lock a key down to those IPs. Talk to your account team to add IP restrictions to a key — we configure it on our side.
#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
Rather than polling our API, you can subscribe to webhooks for events you care about — order status changes, shipping updates, campaign redemptions, invoice events. Each webhook delivers a signed JSON payload to a URL you control.
To set up webhooks, contact your account team. We help you map events to your endpoints and verify signatures.
#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.