Skip to main content

​
Welcome

Juo’s Customer API provides programmatic access to customer-facing subscription data.
It’s a RESTful API that lets authenticated customers interact with their subscriptions and with other customer-related entities.

​
Authentication

Juo’s Customer API supports several authorization methods depending on the environment in which it’s used.

​
Access token

You can obtain an access token by initializing the login flow with Juo. Once the customer completes the login flow, an access token will become available to be used in the Authorization header: 
Authorization: Bearer <access-token>
Contact us at [email protected] if you need help setting up the login flow in your custom portal.

​
Implicit authorization (only in embedded Shopify context)

You can use implicit authorization when using Juo’s Customer API in an embedded portal under a Shopify Storefront. To use the implicit authorization replace the server URL with /apps/juo/api/customer/v1.

​
Delegated Token

You can obtain a Delegated Token through Juo’s Admin API. After acquiring a valid Delegated Token, include it in the X-Delegated-Token header: 
X-Delegated-Token: <delegated-token>

​
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/customer/v1/products?cursor=<next-cursor>>; rel="next",
      <https://api.juo.io/customer/v1/products?cursor=<prev-cursor>>; rel="prev"
The amount of results per page can be set from 1-100 with the limit query parameter where applicable: 
/customer/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 filterable fields on a resource. There is a special rank field that can be used whenever a search query includes a term not bound to a specific field. 
# Sort by creation date descending
/customer/v1/subscriptions?sort=createdAt:desc

# Sort by status ascending and then by creation date descending
/customer/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 form advanced logical queries, like in examples below: 
# Find all active subscriptions containing 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
⌘I