Cratejoy API
Official vendor OpenAPI document · agent-readyE CommerceOrder Managementbasic32 EndpointsREST
For Agents
Manage subscription orders, renewals, cancellations, and shipments for a Cratejoy subscription-box merchant. Use when an agent needs to drive subscription commerce lifecycle actions on Cratejoy.
Use for: Cancel subscription 88241 effective at next renewal, Skip the next box for subscription 4421, Renew a past-due subscription so the customer keeps their box, Apply coupon 'WINTER10' to an active subscription
Not supported: Does not handle merchant signup, payment processor onboarding, or storefront theme editing - use for subscription, order, shipment, and webhook management only.
Cratejoy is a subscription commerce platform that lets brands run subscription-box businesses end to end, and the Cratejoy API exposes its merchant data and lifecycle controls. Across 32 endpoints, the API covers orders, subscriptions and their coupons and metadata, products, shipments, customer addresses, and outbound webhooks. Subscription-specific operations include cancel, reactivate, skip the next renewal, and renew a past-due subscription, which together cover the day-to-day churn and recovery actions a subscription merchant needs. Authentication is HTTP Basic with the merchant's API credentials.
Install Jentic One Beta
Connect the Cratejoy API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Cratejoy API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcratejoy.com%2Fcratejoy" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcratejoy.com%2Fcratejoy" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Cratejoy API.
Cancel, reactivate, skip, or renew a subscription via dedicated lifecycle endpoints
Add or remove coupons on an existing subscription
List, create, and update orders for a Cratejoy storefront
Track shipments associated with a subscription order
Manage customer shipping addresses and update them in place
Create outbound webhooks so external systems are notified on order or subscription events
Use Cases
Patterns agents use Cratejoy API for, with concrete tasks.
★ Subscription Churn Recovery
When a customer's renewal fails because of an expired card, a churn-recovery workflow uses GET /v1/subscriptions/ to find past-due subscriptions and PUT /v1/subscriptions/{sub_id}/renew/ to retry once the customer updates their card. PUT /v1/subscriptions/{sub_id}/reactivate/ wins back customers who cancelled and changed their mind. This cuts involuntary churn without manual intervention.
Find past-due subscriptions via GET /v1/subscriptions/?state=past_due, then for each one PUT /v1/subscriptions/{sub_id}/renew/ and notify the customer of the result.
Skip-a-Box Self-Service
A subscriber decides to skip their next box because they are travelling. A self-service flow calls PUT /v1/subscriptions/{sub_id}/skip/ to skip the next renewal and PUT /v1/subscriptions/{sub_id}/skip/ again to unskip if plans change. This prevents cancellations driven by inflexibility while keeping the customer's plan intact.
PUT /v1/subscriptions/8821/skip/ to skip the next renewal for a holidaying customer, and confirm the response shows the next renewal pushed by one cycle.
Coupon and Promotion Application
Customer support applies a retention coupon to a subscriber thinking of cancelling. POST /v1/subscriptions/{sub_id}/coupons/ adds the coupon to the active subscription, and DELETE removes it later if the promo expires. GET /v1/subscriptions/{sub_id}/coupons/ confirms which coupons are currently applied so support sees the full picture.
POST /v1/subscriptions/{sub_id}/coupons/ with coupon code 'STAY20' for a churning customer, then GET /v1/subscriptions/{sub_id}/coupons/ to confirm the coupon is active.
Shipment and Address Operations
When a customer moves house, an automation updates their primary shipping address with PUT /v1/store/api/customer/addresses/{address_id}/ and confirms next month's shipment via GET /v1/store/api/shipments/. This avoids the box arriving at the wrong address and reduces support tickets.
PUT /v1/store/api/customer/addresses/{address_id}/ with the new street and postcode, then GET /v1/store/api/shipments/?subscription_id=8821 to confirm next month's box ships to the updated address.
Agent-Driven Subscription Concierge
An AI subscription concierge in a brand's support chat resolves common requests end to end: skipping a box, applying a retention coupon, updating shipping address, or renewing a past-due subscription. Through Jentic, the agent finds the right Cratejoy operation by intent and uses the merchant Basic auth credentials without holding them in plain text.
Search Jentic for 'skip a cratejoy subscription renewal', execute PUT /v1/subscriptions/{sub_id}/skip/, and reply to the customer that their next box has been deferred.
Key Endpoints
32 endpoints — cratejoy is a subscription commerce platform that lets brands run subscription-box businesses end to end, and the cratejoy api exposes its merchant data and lifecycle controls.
METHOD
PATH
DESCRIPTION
PUT
/v1/subscriptions/{sub_id}/cancel/
Cancel a subscription
PUT
/v1/subscriptions/{sub_id}/skip/
Skip or unskip the next renewal
PUT
/v1/subscriptions/{sub_id}/renew/
Renew a past-due subscription
POST
/v1/subscriptions/{sub_id}/coupons/
Add a coupon to a subscription
GET
/v1/orders/
List all orders
GET
/v1/store/api/shipments/
List shipments
POST
/v1/hooks/
Create an outbound webhook
PUT
/v1/subscriptions/{sub_id}/cancel/
Cancel a subscription
PUT
/v1/subscriptions/{sub_id}/skip/
Skip or unskip the next renewal
PUT
/v1/subscriptions/{sub_id}/renew/
Renew a past-due subscription
POST
/v1/subscriptions/{sub_id}/coupons/
Add a coupon to a subscription
GET
/v1/orders/
List all orders
GET
/v1/store/api/shipments/
List shipments
POST
/v1/hooks/
Create an outbound webhook
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring Cratejoy by hand means managing its Basic auth header and mapping subscription, order, shipment, and webhook calls across a 32-endpoint surface yourself. Through Jentic you install once, import Cratejoy from the API Directory, store the credentials once, and your agent calls it.
Permission scoping
Cratejoy puts the subscription id in the URL path (/v1/subscriptions/{sub_id}/...), so a rule can pin the agent to acting on subscriptions you allow. You choose the operations it may call, so cancel or renew is not included unless you add it.
Credential isolation
Your Cratejoy Basic auth credentials are stored once, encrypted, by your own Jentic One instance and applied as the Authorization header at execution time. They never enter the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'cancel a Cratejoy subscription' or 'skip the next box', and Jentic returns the matching Cratejoy operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Cratejoy API through Jentic.
What authentication does the Cratejoy API use?
Cratejoy uses HTTP Basic authentication with the merchant's API credentials sent in the Authorization header. Through Jentic, the credentials are stored encrypted in the vault and added to outgoing requests at execution time.
Can I cancel a subscription through the Cratejoy API?
Yes. PUT /v1/subscriptions/{sub_id}/cancel/ cancels an active subscription. To bring it back, PUT /v1/subscriptions/{sub_id}/reactivate/ restarts billing at the next cycle.
How do I skip the next box for a subscriber through Jentic?
Search Jentic for 'skip cratejoy subscription renewal', load PUT /v1/subscriptions/{sub_id}/skip/, and execute with the subscription ID. Calling the same endpoint again unskips, which is useful if the customer changes their mind.
Can I apply a coupon to an existing subscription?
Yes. POST /v1/subscriptions/{sub_id}/coupons/ adds a coupon to an active subscription, and DELETE /v1/subscriptions/{sub_id}/coupon/{coupon_id}/ removes it. GET /v1/subscriptions/{sub_id}/coupons/ lists what is currently applied.
What are the rate limits for the Cratejoy API?
The OpenAPI spec does not declare numeric rate limits. Cratejoy enforces fair-use limits at the merchant level. Production integrations should retry on 429 responses with exponential backoff and avoid tight polling.
Does the Cratejoy API support webhooks?
Yes. POST /v1/hooks/ creates an outbound webhook subscription and PUT /v1/hooks/{hook_id}/ updates an existing one. Webhooks let external systems react to subscription and order events without polling.
Can I limit what my agent is allowed to do with the Cratejoy API?
Yes. Jentic One is self-hosted by you, so your own rules decide which Cratejoy operations the agent may call and which credentials it may use. Because Cratejoy puts the subscription id in the URL path (/v1/subscriptions/{sub_id}/...), your rules can pin the agent to only the subscriptions you allow. You also choose the operations it can run, so a destructive action like PUT /v1/subscriptions/{sub_id}/cancel/ or a billing action like PUT /v1/subscriptions/{sub_id}/renew/ is not available to the agent unless you enable it.
GET STARTED