​
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.

​
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:

SymbolDescription
_Optional whitespace
__Mandatory whitespace
fieldAn identifier ([a-z][a-zA-Z]*)
valueAn 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:

OperatorDescription
: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