Introduction - Developer documentation

Welcome

The Juo Admin API provides programmatic access to manage subscription resources. This RESTful API allows administrators to interact with subscriptions, customers, and other Juo entities.

Admin API SDK is available here.

Authentication

All API requests must include an API key in the X-Juo-Admin-Api-Key header. Tokens can be generated in the Juo admin interface. Keep your API keys secure and never share them.

X-Juo-Admin-Api-Key: your_api_key

Pagination

The API uses cursor-based pagination to handle large result sets. Navigation links are provided in the Link response header, containing URLs for the next and previous pages.

Link: <https://api.juo.io/admin/v1/subscriptions?cursor=<next-cursor>>; rel="next",
      <https://api.juo.io/admin/v1/subscriptions?cursor=<prev-cursor>>; rel="prev"

The amount of results per page can be set from 1-100 with the limit query parameter where applicable:

/admin/v1/subscriptions?limit=10

Sorting

Results can be sorted using the sort query parameter. Multiple sort criteria can be combined using commas. Sortable fields are the same as the filterable fields on a resource, there is a special rank field that can be always used whenever search query includes a term not bound to a specific field.

# Sort by creation date descending
/admin/v1/subscriptions?sort=createdAt:desc

# Sort by status ascending and then by creation date descending
/admin/v1/subscriptions?sort=status:asc,createdAt:desc

Search query language

Resources can be searched / filtered by an expressive query syntax. The search grammar is expressed in EBNF. It uses the following terminal symbols:

Symbol	Description
_	Optional whitespace
__	Mandatory whitespace
field	An identifier (`[a-z][a-zA-Z]*`)
value	An identifier, single quoted string or double quoted string

The syntax can be expressed with the following grammar:

Query       = Disjunction
Negation    = ( "-" | "NOT" ) _ Parenthesis | Parenthesis
Parenthesis = "(" _ Query _ ")" | Term
Disjunction = Conjunction ( __ "OR" __ Conjunction ):+ | Conjunction
Conjunction = Negation ( __ "AND" __ Negation ):+ | Negation
Term        = field Operator value | value
Operator    = ":" | ":<" | ":>" | ":>=" | ":<="

It lets you to form advanced logical queries, some examples below:

# Find all active subscriptions which contain a term "Blue"
status:active AND Blue

# The same as above but with quotes
status:'active' AND 'Blue'

# Find failed subscriptions with PayPal instrument along with all cancelled subscriptions after 2024
(status:failed AND instrument:paypal) OR (status:cancelled AND cancelledAt:>='2024-01-01')

# Find all but active subscriptions
- status:active

Below you can find the meaning of each available operator:

Operator	Description
:	Equal
:>	Greater than
:>=	Greater than or equal
:<	Less than
:<=	Less than or equal

Rate limiting

The API implements a token bucket rate-limiting strategy to ensure fair usage. Each API token has a bucket that fills at a constant rate. API calls consume tokens from the bucket. When the bucket is empty, requests will be rejected until it refills. Rate limit information is included in the response headers:

X-RateLimit-Limit: 1000     # How many requests the client can make
X-RateLimit-Remaining: 999  # How many requests remain to the client in the time window
X-RateLimit-Reset: 60       # How many seconds must pass before the rate limit resets

​Welcome

​Authentication

​Pagination

​Sorting

​Search query language

​Rate limiting