Roster API Documentation

Download OpenAPI specification: Download

The Roster API lets you build on top of the ambassador, affiliate, and referral infrastructure that powers programs for Shopify and ecommerce brands. Use it to sync program members, track referral orders and rewards, manage payouts, and pull the performance data behind your ambassador and affiliate campaigns into your own systems.

This is a REST API. Requests and responses are JSON, resources map to predictable URLs, and it uses standard HTTP verbs and status codes. If you've worked with any modern REST API, this will feel familiar.

Base URL

https://api.getroster.com

API versioning lets Roster keep evolving the platform while giving you a predictable path for feature upgrades and deprecations. v2 is the current version.

Authentication

Every request needs a valid access token in the Authorization header, prefixed with Bearer. Generate and expire tokens in your brand settings.

curl https://api.getroster.com/v2/contacts \
  -H "Authorization: Bearer {token}"

There are two kinds of token. A private token has read/write access to your account data and belongs only in secure, server-side environments. A public token has limited access and works only with the endpoints that need client-side scripting, such as capturing referral link clicks and referred orders; endpoints that accept a public token say so in their reference entry.

Never expose a private token publicly. Do not embed tokens in client-side code or post them anywhere publicly accessible, such as support forums or GitHub. If you believe a token has been compromised, generate a new one in your brand settings and expire the old one.

What you can do with it

• Contacts — create, read, and update the ambassadors and affiliates in a program
• Referrals & orders — track referral links, attributed orders, and conversions
• Rewards — read reward records and update pending reward status
• Programs & campaigns — read program and campaign configuration and performance
• Discount codes — manage discount rules and the codes issued against them
• Webhooks — subscribe to events so your systems react in real time to new contacts, orders, and rewards

Pagination

Some endpoints accept pageIndex and pageSize, with a maximum of 250 per pageSize. Responses from those endpoints include a pagination object alongside the total record count across all pages. Use nextPageIndex to walk the remaining pages; a pageIndex beyond totalPages returns no data.

Rate limits

Requests are counted over a rolling 60-second window, with the allotment replenishing each second based on what was used in the previous 60 seconds. Your limit is determined by your subscription package — contact support to find out your current one. Requests over the limit return 429 Too Many Requests.

Getting started

1. Generate an access token in your brand settings.
2. Make a request to a read-only endpoint to confirm authentication.
3. Set up webhooks if you need real-time updates rather than polling.
4. Browse the endpoint reference below for full request and response schemas.

Building an AI or agent integration? Roster also runs an MCP server, which exposes this functionality to agentic tools directly. See the AI connections guide.