canonical: https://jentic.com/apis/cratejoy.com/cratejoy

# Cratejoy API

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.

## For AI 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.

## Scope

Does not handle merchant signup, payment processor onboarding, or storefront theme editing - use for subscription, order, shipment, and webhook management only.

## Capabilities

- 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

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

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

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

## Key resources

- **Subscriptions** — Manage subscription lifecycle including cancel, reactivate, skip, renew, coupons, and metadata
- **Orders** — List, create, and update orders for the storefront
- **Products** — List and update products in the catalogue
- **Shipments** — List and retrieve shipments associated with orders
- **Addresses** — Create, list, update, and delete customer shipping addresses
- **Webhooks** — Create and manage outbound webhooks for events

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **Shopify Admin API** — Shopify is a general-purpose e-commerce platform with subscription apps available.
- **Recharge API** — Recharge is a subscription commerce platform that runs on top of Shopify and BigCommerce.
- **Shopify Admin API** — Some merchants run both a Cratejoy subscription store and a Shopify retail store and need to keep them in sync.

## FAQ

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